PocketSmith (read-only)

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: accounts without linked scenarios return no data, forecast horizon is bounded by subscription plan date limits, credit-card balances are naturally negative, and long horizons should use monthly resolution to keep responses manageable. These are exactly the non-obvious traits 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?

Sentences are dense and front-loaded with purpose before caveats. A few points (monthly resolution for long horizons, account-type list) are duplicated by the schema descriptions, which is modest redundancy rather than noise.

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 six-parameter, zero-required read tool with no output schema, the description covers purpose, data-availability caveats, parameterization heuristics, and the paired navigation tool. Return-value shape is only gestured at ('shows where each account is heading', danger zones) rather than described, which keeps it short of a 5.

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 cross-parameter meaning the schema does not: danger_threshold must be adjusted for credit accounts because their balances are naturally negative, and resolution should be monthly for long horizons. That is real semantic value beyond field-level docs.

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

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

The description names a specific verb and resource — forward-looking account-level balance projections — with a scope qualifier ('account-level') that implicitly separates it from the aggregate net_worth_forecast sibling. It also states the secondary output (danger zones). It stops short of explicitly naming the sibling it is not, which keeps it from a 5.

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

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

It gives concrete usage context: filter by account types/IDs, use monthly resolution for long horizons, adjust danger_threshold for credit cards, and pair answers with navigate_to_cashflows. There is no explicit 'use this instead of net_worth_forecast/trend_analysis' routing statement, so the alternatives dimension is only implied.

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

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered; the description goes further and discloses the full return payload, including the on_track/at_risk/over_budget vocabulary, the is_bill tagging, and the 14-day event horizon. For a tool with no output schema, this is precisely the behavioral context 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?

Front-loads the purpose, then the return contents, then usage conditions and alternatives — a logical agent-friendly ordering. The dense enumeration of return fields is informative rather than padded; every sentence carries selection-relevant information.

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

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

With no output schema, the description carries the full burden of explaining return values and does so exhaustively, plus clarifies scope (point-in-time, 14-day forward window) and sibling boundaries. An agent can decide and call correctly from this 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?

Only one optional parameter, and the schema already documents its fallback behavior at 100% coverage. The description adds nothing parameter-specific, which is acceptable given the schema does the work, but it doesn't reinforce the auto-resolution of user_id.

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 ('Point-in-time financial health check') and enumerates exactly what comes back (net worth, cash position, spending pace with projection, budget traffic lights, action items, upcoming events). It is clearly distinguishable from siblings like month_end_review and spending_comparison, which it names.

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

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

Gives explicit when-to-use ('quick daily or weekly check-in', 'how am I doing financially RIGHT NOW') and explicitly routes three alternatives to their own conditions: month_end_review for retrospective, spending_comparison for two periods, list_events for events only. Nothing is left to inference.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the description's job is added context — and it delivers: detection methodology (group by payee, regular intervals, consistent amounts), frequency classification, and the shape of the result (estimated annual cost per item plus totals). It omits caveats that matter for a heuristic detector, such as minimum occurrence thresholds or how irregular data produces false positives or misses.

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

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

Purpose is front-loaded in the first sentence and each subsequent sentence adds distinct information: mechanism, return content, use cases, and the navigation warning. It runs long for two optional parameters, but no sentence is filler.

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

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

A read-only, zero-required-parameter analytics tool with no output schema; the description compensates by describing what is returned (per-item annual cost and totals) and by pre-empting the agent's instinct to link to a report page. Nothing needed to invoke or interpret it is missing.

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

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

Schema coverage is 100%: both parameters carry descriptions including the default (6 months) and max (12), plus the auto-resolution behavior for user_id. The description adds nothing about window selection or when a longer lookback helps, so the schema does all the work — 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?

States a specific verb and resource — 'Detects recurring expenses (subscriptions, memberships, regular bills) by analyzing transaction history' — and immediately explains the mechanism (payee grouping, interval/amount consistency, frequency classification). An agent can distinguish this from list_transactions or spending_comparison without opening any schema.

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

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

Gives concrete use cases (subscription audits, forgotten charges, 'am I paying too much for X' comparisons) and an explicit routing instruction: answer from this data rather than offering a navigation link, because no report page maps to subscriptions. That is a named alternative behavior plus the condition that selects it, which is the top of the scale.

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

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

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses two non-obvious behaviors: historical forecast values reflect CURRENT scenario settings rather than what was originally forecast, and accounts without linked scenarios return no comparison data. These are exactly the caveats an agent needs to interpret results correctly and avoid misleading conclusions.

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

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

Purpose is front-loaded in the first sentence, the qualification caveats follow, and every sentence adds information — the 25%+ and 2x+ thresholds and the scenario-settings note are all load-bearing. No repetition of the title or 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 does the work of explaining what the analysis produces (balance comparisons plus categorized inaccuracy drivers) and flags the empty-data case. It stops short of describing the shape of the returned comparison data, which is the only remaining gap for a zero-required-parameter analytical 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 all four parameters (user_id, resolution, account_ids, months_back) are already documented including defaults and the max of 12. The description adds no parameter-level detail, 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 opens with a specific verb and resource: compares actual vs forecast account balances over past periods. It then adds a second, distinct capability (budget inaccuracy drivers with explicit thresholds) and implicitly distinguishes itself from forward-looking siblings like cash_flow_forecast and net_worth_forecast by being a retrospective evaluation.

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 states the use case clearly — 'useful for calibrating current forecast configuration' — which tells an agent when to reach for it. However, it never names an alternative tool (e.g. cash_flow_forecast vs this) or states when not to use it, so routing between the several forecast-related siblings still requires 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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds real value beyond that by explaining the account/transaction-account/scenario hierarchy and the possibility of multiple child transaction accounts, which shapes how an agent interprets the result. It stops short of covering not-found behavior or auth requirements.

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

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

Four tight sentences, front-loaded with the action and then the domain model. The mortgage-with-offset example earns its place by clarifying why multiple child transaction accounts appear, which prevents misinterpretation of the return 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?

There is no output schema, so the description's enumeration of returned fields (title, type, currency, balance, child transaction accounts and scenarios) fills that gap. Combined with annotations covering safety, an agent has everything needed for a one-parameter read.

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

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

Schema coverage is 100% and the single id parameter is fully documented in the schema. The description adds no syntax, format, or lookup semantics beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Gets an account by its ID') and immediately defines the domain object, describing what an account contains (transaction accounts and scenarios). The 'by its ID' scoping makes it distinguishable from list_accounts without opening either schema.

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

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

The single-record retrieval is implied by 'by its ID' and the required id parameter, but the description never explicitly says when to use this versus list_accounts or get_transaction_account, nor what happens if the ID is unknown. Usage is inferable but not guided.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description's genuine addition is the enumeration of returned fields, which is useful because no output schema exists, but it says nothing about not-found handling or permission requirements.

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, zero preamble, with the action front-loaded and the return payload second. The only wasted word is the redundant possessive in 'the attachment's ... file name'.

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

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

Because there is no output schema, the description carries the burden of describing the response and does so with a concrete field list (title, file name, content type, download URL). For a one-parameter read tool this is nearly sufficient; a note on missing-ID behavior would close the gap.

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

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

Schema coverage is 100% for the single 'id' parameter, and the schema already documents it as 'The unique identifier of the attachment.' The description's 'by its ID' restates rather than extends that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Gets an attachment by its ID') that an agent can distinguish from list_attachments, create_attachment, and update_attachment without opening the schema. It is clear but does not explicitly differentiate itself from the sibling 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?

There is no guidance on when to use this single-record fetch versus list_attachments, nor any mention of prerequisites, error behavior for unknown IDs, or alternatives. Usage is only implied by the name and the 'by its ID' 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value by disclosing the return content (per-category budgeted vs actual), the forecast-period scoping, and the roll-up behavior. It stops short of noting edge cases such as users with no configured budget, so it is strong but not exhaustive.

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 purpose and return shape, followed by sibling routing and the page-link pairing. Every sentence carries distinct information and none repeats the annotations.

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, and the description compensates by describing the per-category entry structure and the roll-up effect on it. For a two-parameter read tool with full annotation coverage, an agent has everything needed to call it and interpret the result.

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%: both user_id and roll_up are fully documented, including roll_up's default and its non-obvious behavior of keeping children visible while folding figures into parents. The description's 'Optionally rolls up child categories into their parents' only restates that, 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?

States a specific verb and resource ('Gets the user's budget') plus the scope ('configured forecast period') and the exact return shape ('one entry per category with budgeted vs actual figures'). It is clearly distinguishable from get_budget_summary and navigate_to_budget without opening either 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 routes the agent: use get_budget_summary for analysis over a specific date range, and offer navigate_to_budget as the matching page link. Both alternatives and the conditions selecting them are named, leaving nothing 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context: transfers are excluded from the analysis and results are bucketed into periods. It stops short of describing output fields or how partial buckets at range edges are handled.

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

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

Three sentences, front-loaded with the core action and scope before the differentiation and the navigation hint. Dense but every clause carries information; the parenthetical page-link sentence is slightly tacked-on but still 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 output schema, the description correctly fills the gap by summarizing the return ('actual vs budgeted figures per period bucket'). For a read-only analytical tool with fully documented parameters, an agent has enough to select and call it, though exact response fields remain unspecified.

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 all five parameters are already documented, and the description's fortnightly example essentially restates the interval property's schema text. It adds the useful framing that sub-monthly buckets are the differentiator, but gives no extra detail on date alignment or how interval interacts with period=years.

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 ('Gets the user's budget summary with expense and income analysis') and scopes it ('across all categories (excluding transfers)'). It also explicitly differentiates itself from siblings by claiming to be 'the only analysis tool with sub-monthly buckets', which no other tool name suggests.

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

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

Gives a concrete triggering condition — pay-cycle asks like 'what's left over each fortnight' — and names the exact parameter combination that serves it (period=weeks interval=2). It also routes the agent to the follow-up page-link siblings (navigate_to_budget, navigate_to_income_expense) with a stated purpose for each.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful context by enumerating what the response contains (title, colour, parent, transfer/bill flag), which matters because no output schema exists.

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

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

Two compact sentences: purpose front-loaded, then return contents. Zero filler.

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

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

For a single-entity getter with three annotations and one fully documented parameter, this is close to complete, and the return-field enumeration compensates for the missing output schema. A brief note on behavior for a nonexistent ID would have made it full.

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 a single parameter with 100% schema coverage, so the schema already explains 'id'. The description adds nothing about ID format, validity, or error behavior for unknown IDs; baseline 3 applies for a fully documented single param.

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 ('Gets a category by its ID') and the ID-based scope implicitly distinguishes it from the sibling list_categories. It does not name a sibling explicitly, but the read-a-single-entity framing 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?

Usage is only implied: an agent infers it should call this when it already has a category ID. There is no explicit statement of when to prefer it over list_categories or when it is unnecessary, and no prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds value by enumerating the return fields (name, symbol, decimal places), which matters since there is no output schema, but it says nothing about behavior for an unknown or invalid code.

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 tight sentences: the action first, the return shape second. No filler, no redundancy, and the reader gets the essential facts immediately.

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

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

For a one-parameter read tool with complete annotations and no output schema, the description covers what it does, what it takes, and what it returns. Only the error behavior for a missing currency code is 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 single 'id' parameter is already fully documented with matching examples ('nzd', 'usd', 'gbp'). The description repeats the same examples without adding format rules such as case sensitivity, so baseline 3 applies.

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

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

States a specific verb and resource ('Gets a specific currency by its code') and even previews the return fields. It implicitly contrasts with list_currencies via 'a specific currency', but never names that sibling, so differentiation is inferred rather than stated.

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 use case (look up one currency when you already have its code) is implied by 'by its code', but there is no explicit when-to-use, when-not, or pointer to list_currencies for browsing all codes. An agent must infer the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context by identifying the target as the authenticated user and listing the identity fields returned.

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

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

Three short sentences, each with a clear role: purpose, return contents, and downstream usage. The purpose is front-loaded and nothing is wasted.

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

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

For a zero-parameter, read-only tool with full annotation coverage, the description provides enough detail about what is returned and why to call it. Although there is no output schema, the description enumerates the key return fields.

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

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

The tool has zero parameters, so there are no parameter semantics to document; the baseline for zero-parameter tools is 4. The description 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?

States a specific verb and resource: gets the currently authenticated PocketSmith user. It also enumerates the returned fields, making its purpose distinct from update_user and account-related sibling 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 to use this to obtain the user ID needed by most other tools, giving clear primary-use context. It does not name exclusions or alternatives such as update_user for modifications, so it falls short of a 5.

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

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

The annotations already declare the safe read-only, idempotent, non-destructive behavior, so the description does not need to repeat safety. It adds useful return-value context by naming sync status, last successful sync time, next sync time, provider details, and optional per-connection account details, though it does not mention pagination or error behavior.

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

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

The description is three focused sentences: it states what is returned, what is optionally included, and when to use the tool. It is front-loaded and every sentence contributes without unnecessary 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?

For a simple read-only listing tool with two fully described parameters, rich annotations, and no output schema, the description gives enough detail about return content and optional account inclusion for an agent to call it correctly. No critical calling context appears to be missing.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds some meaning for include_accounts by mentioning balances and transaction update times, but it does not add semantic detail for user_id and largely restates the optional account inclusion 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?

The description gives a specific verb and resource: it lists data feed connections for a user, with sync status, provider details, and optional account details. It is clear what the tool does, but it does not explicitly differentiate itself from the related sibling refresh_data_feeds_connection or clarify that it is read-only status retrieval rather than a refresh 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 final sentence explicitly states when to use the tool: to check whether feeds are healthy, degraded, or need attention. It does not name alternatives or describe when not to use it, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile needs no restating. The description adds useful domain framing (what an event is) but says nothing about behavior on a missing ID or what the response contains.

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, front-loaded with the action and followed by domain context and an ID example. The third sentence overlaps with the schema's own format note, so it is slightly redundant but not wasteful.

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 one required parameter and full schema coverage, the input side is well covered. Since no output schema exists, the description would need to explain return values or not-found behavior, and it does neither, leaving a meaningful gap for a lookup 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% and the schema already documents the single 'id' parameter including its 'number-timestamp' format. The description repeats that format and adds one concrete example, which is marginal added value beyond the schema rather than new semantics.

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

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

The description gives a specific verb+resource ('Gets a budget event by its ID') and explains that events are recurring or one-off income/expense entries used in forecasting. 'By its ID' implicitly distinguishes it from list_events, but no sibling is named, so it falls just short of the top score.

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?

Retrieval-by-ID is implied by 'by its ID', which suggests use when you already have an identifier rather than when browsing. However, it never states when to prefer this over list_events, nor what to do when the ID is unknown, leaving usage 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, idempotentHint=true, destructiveHint=false and a closed-world scope, so safety is covered. The description adds value beyond them by disclosing the returned fields (title, currency, creation date), which matters since there is no output 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?

Two short sentences, zero filler, with the primary action front-loaded and the return payload following. Every clause earns its place.

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

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

For a simple one-param read tool with full annotations and complete schema coverage, the description covers purpose and return fields well. Minor gap: no mention of what happens when the ID doesn't exist (error vs empty result).

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

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

Schema coverage is 100% and the single 'id' parameter is fully documented in the schema. The description adds only the notion that it identifies an institution, so the baseline of 3 applies – nothing extra on format or lookup failure behavior.

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 ('Gets') and resource ('financial institution') plus the lookup key ('by its ID'), which distinguishes it from list_institutions and create/update/delete_institution siblings. It doesn't explicitly name the alternative list tool, but the single-entity framing 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?

Usage is implied by 'by its ID' – fetch one known institution rather than enumerate. There is no explicit when-to-use/when-not guidance and no reference to list_institutions for the browse case, so an agent must infer the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is fully covered. The description adds genuinely useful behavioral context by enumerating the fields returned (date, payee, amount, category, labels, note, memo, review status), which matters because there is no output 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?

Two short sentences, zero filler, with the core purpose front-loaded and the return-field detail following. 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 one simple parameter and no output schema, the description does the heavy lifting by sketching the return payload. It still leaves open what happens when the ID does not exist (error vs null), which is the one thing an agent might need to know before calling.

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

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

Schema coverage is 100% and the single parameter is documented as "The unique identifier of the transaction." The description only restates that the ID identifies a single transaction, adding no format, type, or error semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("Gets a single transaction by its ID"), and the word "single" plus the ID requirement implicitly distinguishes it from list_transactions. It does not explicitly name the sibling, so it falls short of a 5.

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

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

Usage is only implied: an agent can infer it should call this when it already has a transaction ID, but the description never says so, never mentions list_transactions or search as the alternative for finding a transaction, and gives no exclusions or preconditions.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the returned fields (name, number, type, currency, current and starting balance) and the parent/child data model, which is exactly the behavioral context annotations cannot convey.

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

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

Front-loaded with the action and identifier, followed by two short sentences of domain context and one listing return fields. Every sentence carries information, though the entity-model explanation is slightly more than strictly required for a single-parameter lookup.

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, and the description compensates by enumerating the returned fields, so an agent knows what a successful call yields. It omits error behavior (e.g., unknown ID) and the sibling routing question, which keeps it below 5 for a tool in such a crowded namespace.

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 'id' parameter, so the baseline is 3. The description restates that lookup is by ID but adds no format, range, or failure semantics beyond what the schema already says.

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 ('Gets a transaction account by its ID') and defines the domain entity, including its relationship to a parent account and institution. It stops short of distinguishing itself from nearby siblings like get_account or list_transaction_accounts, which an agent would have to infer from names alone.

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

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

Usage is only implied by 'by its ID'. There is no statement of when to use this instead of get_account, list_transaction_accounts, or get_institution, and no prerequisites or exclusions are given, despite several look-alike siblings in the toolset.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description's one behavioral addition, that it analyses all user scenarios by default, largely restates the scenarios parameter description in the schema. No mention of result size, rate limits, or behavior for very wide date ranges.

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 front-loaded sentences that open with the verb and resource, then the data shape, then the companion link. The sentence about default scenarios is somewhat redundant with the schema wording, but the definition is tight overall.

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, fully schema-documented tool with no output schema, the description supplies enough: what data comes back (actual vs budget per bucket over time), the default scenario scope, and the paired navigation tool. Minor gaps are how results are ordered or whether large ranges are truncated.

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 every parameter including the interval-with-period example and scenario defaults is already documented. The description restates the date-range and category scoping but adds no syntax or format detail beyond the schema, making the baseline of 3 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?

Names a specific verb and resource (gets income/expense budget trend analysis) and then defines the output conceptually: per-bucket actual vs budget for chosen categories over time. That distinguishes it from analysis siblings such as get_budget_summary or spending_comparison and from the navigation sibling navigate_to_trends.

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 that navigate_to_trends is the matching page link to offer alongside the answer, which gives a clear pairing rule. It also states the default scope (all user scenarios) to guide invocation. It stops short of saying when to prefer spending_comparison or get_budget_summary instead, so no explicit exclusion is given.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful domain context about what an account represents and the ID lookup requirements, but it does not describe pagination, return shape, or whether both IDs may be supplied.

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

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

Four compact sentences are front-loaded with the action, followed by the key constraint, the domain definition, and the ID lookup guidance. There is no redundant or wasted wording.

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

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

For a read-only listing tool with full schema description coverage and annotations covering safety, the description supplies enough context to invoke it correctly. Minor gaps remain around pagination or whether both parameters can be combined, but nothing critical is missing.

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

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

Schema coverage is 100%, but the description adds important semantics beyond the schema: it states that at least one of user_id or institution_id is required, whereas the schema marks neither as required. It also explains how to obtain valid IDs, adding real value over the schema field descriptions.

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

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

The description uses a specific verb and resource ('Lists accounts') and clarifies that accounts are containers for transaction accounts and scenarios, which helps distinguish them from sibling concepts such as list_transaction_accounts. It does not explicitly route the agent to other account-related siblings like get_account or list_transaction_accounts, so it falls short of full sibling differentiation.

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

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

It clearly states the key usage constraint that either user_id or institution_id is required, and it names get_current_user and list_institutions as sources for those IDs. It lacks an explicit when-to-use-this-vs-alternatives statement for other account-listing tools, but the prerequisite guidance is strong.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description earns credit for adding the "either user_id or transaction_id" constraint, which the schema does not enforce (required is empty), but says nothing about result size, pagination, or whether unassigned=true is rejected when transaction_id is used.

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, zero filler, with the '{resource} lists' framing and the required-filter constraint front-loaded. Nothing could be cut without losing 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?

A small read-only list tool with rich annotations and no output schema does not need much, and the description covers the essential calling constraint. Minor gaps remain around result caps and what happens with invalid parameter combinations.

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 all three parameters are already documented with the same semantics the description provides. The description's phrasing mirrors the schema almost verbatim and adds no syntax or edge-case detail beyond it; baseline 3 applies.

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

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

States a specific verb and resource ("Lists attachments") and immediately adds the scoping constraint. It is distinguishable from get_attachment and its list_* siblings by resource name alone, though it never names an alternative explicitly.

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

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

Gives clear applicability conditions: one of user_id or transaction_id is required to call it, and unassigned only applies when using user_id. It stops short of saying when to prefer this over get_attachment or list_transactions, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuine context beyond that: the data is hierarchical (parent/child) and it enumerates what comes back (ID, title, colour, type, parent), which matters given there is no output 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?

Three short sentences, front-loaded with the core action, then hierarchy, then return shape. No filler; each sentence adds a distinct fact, though the return-field sentence could be tightened.

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 one-parameter read tool with full annotation coverage and no output schema, the definition is adequate: it names the scope, the hierarchy trait and the returned fields. It still omits whether inactive/archived categories are included, ordering, pagination, and whether children are nested or flat — meaningful gaps an agent would otherwise have to discover by calling.

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 a single parameter, user_id, documented at 100% schema coverage, so the schema already carries the semantics. The description only echoes the user scoping and adds no format or edge-case detail (e.g. whether omitted user_id defaults to current user). Baseline 3 applies when 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?

States a specific verb and resource ('Lists all categories') plus scope ('belonging to a user') and adds that results are hierarchical. It is clearly distinguishable from mutation siblings like create_category/update_category, though it never contrasts itself with get_category or list_category_rules.

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

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

Usage is only implied by the phrase 'belonging to a user' — the agent can infer this is a bulk read for one user's categories. There is no explicit when-to-use versus get_category (single item) or list_category_rules, and no stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered by structured data. The description contributes domain context (rules auto-assign categories via payee matching) but says nothing about return shape, ordering, or whether the list is unfiltered/paginated.

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, zero waste: the action and scope come first, followed by the minimal domain definition needed to know what is being listed. Nothing redundant or padded.

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

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

For a one-parameter read tool with full annotation coverage and no output schema, the description is essentially sufficient; it explains the entity being returned. Minor gap: no mention of ordering or whether an empty list is possible.

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?

Single parameter with 100% schema description coverage, so the schema already explains user_id. The description only implies scoping ('belonging to a user') and adds no format or edge-case detail beyond that, 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 (Lists) and resource (category rules) scoped to a user, and the second sentence defines what a category rule is, which materially aids recognition. It does not explicitly differentiate from the adjacent list_categories or create_category_rule, so it stops short of a 5.

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

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

Usage is only implied: an agent can infer this is the read path for inspecting existing rules (e.g. before create_category_rule or to audit payee patterns), but the description never says when to use it or when a different tool is preferable. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is fully covered elsewhere. The description's only added behavioral value is the return shape (codes, names, symbols), which matters because there is no output schema, but it says nothing about ordering, caching, or volume of results.

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

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

Two short sentences, front-loaded with the operation and scope, with the return contents second. No filler or restated annotation text.

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 and no output schema, the description needs to convey what comes back, and it does at a high level. A note on ordering or result size would close the remaining gap, but nothing required for a correct call 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 tool takes zero parameters, so there is nothing to disambiguate. The description correctly signals a no-argument enumeration rather than leaving the agent to guess whether filters exist.

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 ('Lists all currencies supported by PocketSmith') and names the returned fields. It implicitly distinguishes itself from the singular sibling get_currency via 'all', but never names that sibling explicitly.

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

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

Usage is only implied: an agent can infer this is the enumeration endpoint and get_currency is for a single lookup. There is no explicit when-to-use, when-not-to-use, or statement that no filtering/pagination options exist.

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, idempotentHint=true, openWorldHint=false, so the safety profile is covered. The description adds domain behavior (what events are, how a scenario relates to an account) and the either/or identifier requirement, but says nothing about result limits, pagination, or what happens when both IDs are supplied — notable since the schema requires neither ID.

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 the key constraint in the first two sentences; the remaining two sentences explain the domain. The final sentence about scenarios belonging to accounts is mildly tangential but still aids interpretation of scenario_id.

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 full schema coverage and no output schema, this is nearly complete: purpose, identifier constraint, and domain model are all present. Missing only edge-case behavior (both IDs supplied, neither supplied, result volume).

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

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

Schema coverage is 100%, so 3 is the baseline, and the description earns above it by surfacing the either/or relationship between user_id and scenario_id, which the schema does not state (the required array lists only the two dates). It does not clarify what happens if both or neither are passed.

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 ('Lists budget events') plus scope ('within a date range'), and explains what an event is. It is clearly a filtered list rather than get_event or create_event, though it never names a sibling explicitly.

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

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

'Requires either user_id or scenario_id' gives an eligibility constraint, which is real usage guidance. But it never says when to prefer user_id vs scenario_id, or when to use this instead of get_event / cash_flow_forecast / find_recurring_expenses, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, covering the safety profile. The description adds structural context (institution contains accounts) but does not mention pagination, ordering, auth requirements, or return format.

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

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

Two sentences, front-loaded with the core action, and no wasted words. Each sentence provides useful context.

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

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

For a simple list tool with one fully documented parameter and rich annotations, the description is nearly complete. It could mention pagination or return ordering, but those are minor given the low complexity.

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% for the single user_id parameter, so the schema fully documents it. The description adds no further detail about the parameter, which is acceptable at this coverage level.

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 ('Lists') and resource ('financial institutions'), and adds that each institution represents a bank and contains accounts. It implicitly distinguishes from 'get_institution' by saying 'all', but does not explicitly name siblings or exclusions.

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

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

No guidance on when to use this tool versus alternatives like get_institution, list_accounts, or create_institution. The implied use case is retrieving all institutions for a user, but no conditions or exclusions are 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is fully covered. The description adds genuinely new lifecycle context — labels exist implicitly and are created via create_transaction/update_transaction — which explains why there is no create_label sibling. It stops short of any return-shape or ordering detail.

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

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

The core action is front-loaded in the first clause, and the following sentences each add distinct value (definition, routing guidance, lifecycle). The middle sentence is dense and packs definition, example use cases, and a sibling reference together, slightly hurting scannability, but nothing is wasted.

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

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

For a one-parameter read tool with no output schema, the description covers purpose, taxonomy placement, routing, and creation lifecycle — everything needed to decide and call correctly. It doesn't characterize what a returned label object contains, but with annotations and a simple schema present that is a minor gap.

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

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

There is a single required user_id at 100% schema description coverage, so the schema carries the parameter semantics fully. 'Belonging to a user' reinforces the scoping but adds no syntax or format detail beyond what the schema states. Baseline 3 applies.

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

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

States a specific verb and resource ('Lists all labels belonging to a user') and immediately defines what a label is, distinguishing it from categories: free-form tags that span categories. It also names the sibling whose search already matches label text (list_transactions), so an agent can tell the tools apart without opening either schema.

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

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

Gives an explicit when-to-use condition: 'check here when a pull together my work expenses style ask has no matching category,' and names the alternative path (list_transactions search matches label text). It also covers the when-not case by pointing to categories as the primary taxonomy.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds the non-obvious behavioral limit that saved searches are inert data rather than executable queries, plus how the returned ID is consumed downstream. It stops short of describing pagination or the exact shape of each returned record.

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, front-loaded with purpose, then definition, then the actionable constraint. No filler and nothing repeated from the annotations or 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 carries some of the return-value burden and does so partially by referencing 'returned filter criteria' and 'numeric ID'. What it omits is the full set of returned fields (e.g. name, id, filter contents), which an agent planning the follow-up list_transactions call would benefit from.

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?

Only one parameter (user_id) with 100% schema description coverage, so the schema already carries the semantics. The description adds no per-parameter detail such as whose user_id is expected or whether it defaults to the current user, which would be the only way to exceed the baseline here.

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 ('Lists saved searches belonging to a user') and immediately defines the domain term ('pre-configured transaction filters'), which separates it from list_transactions and the other list_* siblings. An agent knows exactly what this returns 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 states the key constraint ('cannot be executed via the API') and names two concrete alternatives with their conditions: pass the filter criteria to list_transactions manually, or open in the app via navigate_to_transactions with the numeric ID. This is textbook when/when-not routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds no behavioral context of its own, such as whether the full set is returned in one call or whether results are cached, so it meets but does not exceed the annotated baseline.

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

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

One short sentence with the resource front-loaded and no filler. For a trivial enumeration endpoint this is exactly the right size.

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

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

Given a parameterless, annotated read tool, the description is nearly sufficient. The one gap is that with no output schema it does not say what form the values take (IANA identifiers vs. display names), which an agent building a request would want to know.

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

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

The tool takes zero parameters, so there is nothing to document beyond what the empty schema already shows. Baseline 4 applies; no parameter semantics are needed or missing.

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 (lists) and resource (time zones) scoped to PocketSmith, so it cannot be confused with any sibling tool. It stops short of explicitly differentiating from near neighbors like list_currencies, but the resource uniqueness makes ambiguity essentially zero.

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

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

Usage is only implied: an agent can infer this is a static reference lookup (e.g., to resolve a time-zone value before creating or updating an account). There is no explicit when-to-use or when-not guidance, and no pointer to which sibling operations consume these values.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful domain context about the parent/child account relationship, but says nothing about result size, pagination, or ordering for what could be a long list.

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

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

Four short sentences, front-loaded with the action, then the domain definition, then the prerequisite hint. Nothing is redundant and no sentence could be removed without losing 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 simple, single-parameter read tool with full annotation coverage and no output schema, the description covers purpose, domain model, and parameter sourcing. The only gap is that it doesn't hint at what fields a transaction account record contains or how many might return.

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

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

Schema coverage is 100% and the single user_id parameter is documented in the schema. The description goes beyond it by telling the agent how to obtain the value (via get_current_user), which is real workflow value rather than a restatement.

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 ("Lists all transaction accounts for a user") and adds a conceptual definition — transaction accounts hold actual transactions and each belongs to a parent account container. This implicitly separates it from list_accounts (containers) and get_transaction_account (single item), though no sibling is named outright.

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 one concrete prerequisite — "Use get_current_user to obtain the user ID" — which is genuinely actionable. However, it never states when to choose this over list_accounts or get_transaction_account, so the selection guidance is only implied by the domain explanation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so safety is covered. The description adds genuine behavior beyond that: pagination defaults and max, the at-least-one-filter constraint, and the literal substring-matching semantics with real matching pitfalls ('filler words like refund ... match nothing'). It stops short of describing the response shape or total-count behavior.

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

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

The precondition and pagination facts are front-loaded, and each sentence carries information. It is somewhat long and the search semantics are restated in both the description and the `search` property, which is mild redundancy rather than waste.

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

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

For a 13-parameter, zero-required read tool with no output schema, the description covers the constraint, filtering model, pagination, and alternatives well enough to call correctly. It does not say what a transaction record contains, which matters slightly more here because there is no output schema to fall back on.

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 schema coverage at 100%, a baseline 3 is warranted, but the description goes further on the highest-risk parameter by explaining that search terms are space-separated, ANDed, substring-matched across named fields, with worked examples ('epartner 36' = payee + amount fragment) and a warning against filler words. The remaining parameters are left entirely to the schema.

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

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

The description opens with a specific verb+resource ('Lists transactions') plus scope ('with pagination, default 30/page, max 100'), and later distinguishes itself from both get_transaction (single record, implicitly) and navigate_to_transactions. An agent can route correctly without opening the schema.

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

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

It states a hard precondition ('Requires at least one of user_id, account_id, category_id, or transaction_account_id'), an explicit exclusion ('the richer in-app search ... is not available via the API — offer navigate_to_transactions for those'), and names the exact sibling tools to call to obtain each ID. This is when/when-not/alternatives guidance in full.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is clear. The description adds useful behavioral context by enumerating the returned financial summary components and stating the output is structured for summarization and sharing, though it does not discuss data freshness or auth requirements.

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 return content, then usage exclusions, then companion link guidance. Although rich, every sentence carries useful information for a complex read-only report 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?

Given a three-parameter, read-only report tool with no output schema, the description is complete: it names use cases, alternatives, returned data categories, summarization suitability, and the matching page link. Nothing essential for correct invocation 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 user_id, start_date, and end_date are already documented with formats and defaults. The description reinforces that it works for 'any date range' and one period, but adds no syntax or edge-case meaning 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 states a specific resource and scope: a comprehensive financial review for any date range, with detailed returned content. It explicitly distinguishes this tool from spending_comparison, financial_health_snapshot, and navigate_to_income_expense, so an agent can identify its role among 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 gives explicit when-to-use guidance: retrospective on ONE period, monthly reviews, quarterly check-ins, 'where did my money go last month'. It also names alternatives for two-period comparison and right-now health checks, and mentions the matching navigation link.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond them — the page always shows all accounts, there is no single-account filter, and institution_id can narrow to one bank — but does not say anything about how navigation manifests (new view, replaced state) or what happens with an out-of-range month.

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?

Strongly front-loaded: purpose, then routing cues, then alternatives, then constraints. It is on the longer side; the parenthetical URL path and the four example queries are useful but the path is arguably expendable, keeping it just short of fully tight.

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 navigation tool with zero required params, no output schema, and full annotation coverage, nothing an agent needs is missing: purpose, disambiguation from siblings, and the absence of account-level filtering are all stated.

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

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

Schema coverage is 100%, and the schema already documents year/month omission, the grouped vs. institution_id exclusivity, and default-to-all behavior. The description mostly echoes that ('Omit year/month for current balances', 'pass institution_id to narrow to one bank'), adding only marginal nuance about when the bank is known, 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+resource (deep link to Account Summary) with the URL path and exactly what the page contains — per-account balances and recent activity as of a chosen month. It explicitly distinguishes itself from navigate_to_net_worth and navigate_to_cashflows, so an agent can route without opening a schema.

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

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

Gives concrete selection triggers with example user phrasings ('how much is in my savings', 'my ANZ balance', 'what were my account balances at the end of March') and names the two alternative tools with the conditions that select them (overall worth vs. money in/out). It also discloses a real constraint up front: no single-account filter exists.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds meaningful context beyond them: what the landed page displays (progress bars, surplus/deficit, rollover, per-category table) and the constraint that it lands on the whole budget with no single-category filter. It doesn't cover return payload or how params alter the rendered page, keeping it off 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-loaded with the destination and scope, then examples, then alternatives. The run of example questions is helpful but slightly padded; still, every clause is relevant and nothing is filler.

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

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

For a navigation tool with no output schema, rich annotations, and 100% schema coverage, the description supplies what an agent still needs: what page is reached, what it shows, and how it differs from adjacent navigations. Nothing required to select or call it correctly is missing.

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

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

Schema description coverage is 100%, so all seven parameters (roll_up, date ranges, inherit_date_range, include_uncategorised, include_rollover_amounts) are fully documented in the schema. The description adds no parameter-level guidance beyond what the schema states, 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 action (deep link to the Budget page at /budget), the resource, and the scope (ONE period, whole budget with no single-category filter). It explicitly names sibling navigations it is not (navigate_to_trends, navigate_to_income_expense), so an agent can disambiguate without opening schemas.

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

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

Gives concrete triggering asks ('am I on budget this month', 'how much is left in my grocery budget') plus explicit alternatives with the condition that selects them (trends over time, actual-vs-budget read-out). When-to-use and when-not are both covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the lower bar applies; the description still adds non-obvious behavior — the view is forward-looking and past actuals are off by default, and the id filters are inverted internally so callers must pass the items they want visible. It stops short of saying what the call actually returns (a URL, a navigation event) or whether it mutates saved UI state when omitted filters are used.

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 destination and view, then triggers, then alternatives, then parameter caveat — a sensible order. It is a dense single paragraph and the filter-inversion sentence partially duplicates what the schema already states, but no sentence is pure filler.

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

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

For a zero-required-parameter read-only navigation tool with fully documented schema, the description covers purpose, routing, and the one surprising behavioral trait. The only gap is that the return value (what a 'deep link' navigation produces) is implied rather than stated, which matters slightly since there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns one extra point by explaining the counterintuitive inversion ('the app inverts them internally — always pass what you want visible'), which is the single most likely parameter mistake. However, the year/month guidance ('omit for the current month') largely restates the schema text rather than adding new semantics.

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

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

Names a specific verb and resource ('Deep link to the Calendar (/calendars)') and immediately characterizes the view: a month grid of scheduled/forecast budget events with a projected daily closing balance. It also explicitly contrasts itself with navigate_to_cashflows and navigate_to_transactions, so an agent can route without opening sibling schemas.

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

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

Gives an explicit 'pick this for' trigger with four concrete example asks ('what bills are due this month', 'when's my next paycheck', etc.), plus named alternatives with the conditions that select them (aggregate multi-month projection → navigate_to_cashflows; past actuals → navigate_to_transactions). When-to-use, when-not-to-use, and alternatives are all present.

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

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

Beyond the read-only and idempotent annotations, it discloses that the target is a spreadsheet-style table, that future months show forecast only, and that the date pair can span multiple years in the past or future. It also warns that named ranges are not resolved, which is useful behavioral context for correct invocation.

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 destination semantics, and the usage examples are valuable. It is slightly repetitive around the explicit start_date+end_date requirement, but otherwise dense and task-focused.

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

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

Given a navigation tool with no output schema and fully described input schema, the description is complete: it explains the destination view, the forecast-vs-actual behavior, date-range constraints, and when to choose sibling navigations instead. Nothing critical for correct selection or invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds useful meaning by stating that start_date and end_date are required together, define month columns, can span any horizon, and do not accept named ranges, though it leaves account_ids and scenario_ids mostly to 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 gives a specific verb and resource: 'Deep link to the Cashflows statement (/cashflows)'. It also explains the destination is a month-by-month table, not a chart, and names sibling navigations it is distinct from.

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 pick this for projection, affordability, and liquidity asks, with concrete example questions such as 'what will my balance be at Christmas'. It also routes the agent away to navigate_to_income_expense, navigate_to_trends, navigate_to_net_worth, and navigate_to_calendar for adjacent 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 readOnly/idempotent/non-destructive, so the description focuses on the non-obvious semantics: a date range is aggregated into a single column set rather than a time series, and only_category_ids/group_ids are inverted by the app so the caller must pass what they want visible. Those two quirks would otherwise cause silent wrong results, and they are disclosed up front.

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, then selection criteria, then sibling boundaries, then the inversion caveat — a sensible priority order with no filler. It is dense and somewhat long, with mild repetition between the report-shape sentence and the example-query sentence, but every sentence carries usable 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?

All 11 parameters are schema-documented, there are no required params, and no output schema exists — so the description compensates by describing the rendered result (columns, subtotals, Net Income total), which is exactly the missing return-value context. Nothing material for correct invocation is absent.

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 a bump by re-emphasizing the counterintuitive inversion of only_category_ids and group_ids ('pass what you want visible') and by clarifying that widening date_range_key merely sums more into the same columns. It does not add meaning for nesting, roll_up, transfers, percentages, or the rollover flags beyond what the schema says.

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 ('Deep link to the Income & Expense report (/income_expense)') and immediately defines what that report is: a budget-vs-actual P&L for one period. It then enumerates the output shape (Income/Expense sections, one row per category with Budgeted/Actual/Difference, subtotals, Net Income), which makes it unmistakable against 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?

Explicitly names the selection condition ('Pick this for breakdown / where-did-it-go asks') and gives four concrete example utterances. It also routes away to three named alternatives (navigate_to_trends for one category's trend, navigate_to_budget for budget management, navigate_to_transactions for raw transactions), so both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description still adds value beyond that: it clarifies this is a deep link (no mutation), that non-bank assets and debts are included, and that the chart is opt-in. It stops short of describing what the caller experiences after navigating, keeping it at a 4.

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 identifying sentence and the routing sentence are front-loaded and the alternative tools are grouped at the end. It is somewhat long with a dense list of quoted example queries, but each clause conveys routing or scope information rather than filler.

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

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

For a zero-required-param, closed-world navigation tool with a fully described schema and no output schema, the definition covers scope, inclusions/exclusions, sibling routing, and the current-month default. 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 coverage is 100%, so every parameter is already documented in structured form. The description only adds the default behavior for year/month ('omit both for the current month'), which is largely a restatement of the schema text, 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?

States a specific action (deep link) on a specific resource (Net Worth page) and defines exactly what the page represents: assets minus debts for a month plus an optional over-time chart. It also explicitly carves itself out from siblings like navigate_to_account_summary, the spend tools, and navigate_to_cashflows, so an agent can route without opening another 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 concrete when-to-use phrasings ('what am I worth', 'assets vs debts', 'am I better off than last year') and names three explicit alternatives with the conditions that select them. Nothing is left to inference about which navigation tool to pick.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavior beyond that by framing the tool as a deep link/navigation action and explaining that token sets the base set while keyword/category/date filters refine 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 definition is front-loaded with what it returns and when to use it, followed by intent examples and the report-tool alternative. It is dense and useful, though the long list of examples is slightly more verbose 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?

For a read-only navigation tool with no output schema, the description covers purpose, selection criteria, and how the main parameters combine. It is nearly complete, with the only notable omission being how it differs from the sibling list_transactions for raw transaction retrieval.

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 carries detailed parameter semantics, including the token forms. The description adds useful composition semantics beyond the schema: token establishes the base set, and keyword/category/date filters optionally refine it.

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: a deep link to a transactions search over raw individual line-item records, with concrete fields listed. It clearly distinguishes the line-item scope from aggregate reports, so an agent can understand what this tool is for even without opening the schema.

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

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

Gives strong when-to-use guidance with several user-intent examples ('show me the transactions for X', 'what did I buy at Y', duplicates/transfers, uncategorised, review) and explicitly routes totals/breakdowns/trends/charts to report tools. The main gap is that it does not name the sibling list_transactions, which is the closest alternative for raw transaction retrieval.

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, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds genuine non-obvious behavior: the chart renders per-period actual bars, a budget overlay, an average line and a rollover band, and the bucket count is derived from range ÷ width rather than supplied. It does not clarify what the 'deep link' returns, but for a read-only navigation tool that is a minor omission.

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 definition before usage examples and alternatives, and every sentence carries routing or semantic information. It is a dense single paragraph, though — the quoted example phrasings could be trimmed without losing routing 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?

Nine parameters (all optional), no output schema, and full schema coverage — the description still covers the gaps that matter: which sibling to pick, how the window is bucketed, how to resolve a category, and how to model a two-period comparison. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by disambiguating the most error-prone parameter — period_quantity is the bucket width multiple, NOT the bucket count — and by stating that omitting category_id means all categories combined and that type selects income OR expense. It also prescribes list_categories to resolve a name to an ID, which the schema does not say.

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

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

Opens with a specific verb+resource ('Deep link to the Trends report') and immediately scopes it: one category's spending/earning over time, or all categories combined when category_id is omitted. It explicitly separates itself from navigate_to_income_expense and navigate_to_budget, so an agent can route without opening the schema.

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

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

Gives the selection rule ('Pick this for over-time / comparison / history asks'), four concrete user-phrasing examples, and named alternatives with the conditions that select them (multi-category one-period breakdown → navigate_to_income_expense; budget management → navigate_to_budget). It even handles the edge case of comparing two periods by prescribing one custom window with monthly buckets.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses that the user-level balances endpoint aggregates ALL accounts (not just those flagged is_net_worth), that growth metrics use simple average monthly change rather than CAGR so zero-crossing net worth works, that omitted milestones auto-detect the next 3 round-number thresholds, and that subscription plan limits may restrict the date range.

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

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

Purpose is front-loaded in the first sentence, followed by return contents, implementation caveats, the sibling alternative, the plan-limit warning, and the page-link hint. Every sentence carries information an agent would otherwise have to guess; 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?

There is no output schema, and the description fills that gap by enumerating what is returned (historical trend, forecast projection, growth metrics, milestone projections). Combined with the annotations covering safety and the routing to cash_flow_forecast, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning by scoping milestones to total net worth and clarifying the auto-detection behavior and its alternative tool. It does not add further detail on resolution or months_back/months_ahead beyond the schema's own defaults and plan-limit note.

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 ('Projects net worth trajectory') and defines scope precisely: past history plus future forecast, returning trend, projections, growth metrics and milestones. It is immediately distinguishable from cash_flow_forecast and navigate_to_net_worth, both of which are named.

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

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

Explicitly routes the agent: milestones apply to TOTAL net worth only, and per-account target tracking (e.g. an emergency fund hitting $10k) must use cash_flow_forecast with account_ids instead. It also names navigate_to_net_worth as the page link to pair with the answer, so both the data call and the follow-up action are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's value lies in return-shape disclosure, which it delivers: totals, category and payee breakdowns, and new/disappeared payee detection. Without an output schema, that enumeration is the only way an agent knows what comes back. The transfer-exclusion rule is an additional behavioral trait not present in annotations or schema.

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

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

Front-loaded with the core action and return shape, then scope, then routing guidance. The parenthetical example ('am I spending more on X than last year') and the sibling routing sentence both earn their space; nothing is redundant 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?

For a six-parameter read-only analytics tool with no output schema, the description supplies the missing half: what is returned, what is excluded, and which sibling to use instead. An agent has enough to select and call it correctly, with only the period-ordering convention as a residual gap.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns one more by explaining that category filtering is optional and that the default is all non-transfer categories. It does not clarify which of period A or B is the baseline/current period, so the direction of any 'more vs less' result is left to inference.

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 ('Compares spending between two date periods') and enumerates the outputs: overall totals, per-category, per-payee, and new/disappeared payees. The 'Excludes transfers' clause further narrows scope so an agent can distinguish it from month_end_review or get_trend_analysis 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?

Names the alternatives explicitly and the conditions that select them: month_end_review for a single period's breakdown, financial_health_snapshot for a right-now check, and navigate_to_trends as the companion link. It also gives concrete use cases (month-over-month, year-over-year) that map directly to the required date parameters.

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