ValYou

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, but the description adds material behavior the annotations cannot convey: no account numbers, masks, or credentials are returned, and property accounts appear regardless of the net-worth toggle with in_net_worth signalling the current state. It also defines the empty:true contract and the next_step_url follow-up, which is exactly the kind of non-obvious behavior 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 what the tool returns, then layers the genuinely non-obvious caveats (property valuation, net-worth toggle, empty result handling). Every sentence is substantive, though the property-valuation explanation is dense and slightly longer than strictly necessary.

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

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

With no output schema, the description carries the full burden of explaining return contents, and it does: field list, the special property case, the privacy exclusion of account numbers/credentials, and the empty-result protocol. An agent can call this and correctly interpret both populated and empty responses.

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 one optional parameter with 100% schema description coverage, so the schema already documents `month` as 'YYYY-MM, optional'. The description never references the month parameter at all, adding no extra semantics, but per the high-coverage baseline a 3 is appropriate since the schema carries this load.

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 the user's accounts') and enumerates the returned fields: category, currency, balance (original + base), and net-worth inclusion. It is clearly distinguishable from siblings like get_net_worth and get_balance_history, which cover aggregate and historical views rather than the account roster.

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 operational guidance: when in_net_worth is false you can offer to include the property account, and when empty:true you should relay the message and next_step_url instead of treating it as an error. It stops short of explicitly contrasting when to call this versus get_net_worth or get_balance_history, so it is clear context without full alternative 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 cover the safe-read profile (readOnly, idempotent, non-destructive, closed-world), and the description layers on substantial extra context: the 'rough' confidence threshold at 6 months, that home_equity is always populated and independent of the user's setting, that negative values mean underwater, and that empty:true is a normal data-absent state with a message and next_step_url rather than an error. This is exactly the beyond-annotations detail the dimension rewards.

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 first few sentences are front-loaded and efficient, describing the return payload well. The back half, however, repeats the same property-setting instruction four times ('never override it', 'still say so plainly', 'Never imply the user has no property', 'offer to include property'), which bloats a tool whose only input is one optional integer.

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

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

With no output schema, the description carries the burden of describing returns and does so capably (net_worth, home_equity semantics, forecast, empty case). Minor gaps remain: the forecast field names/shape, the default value of 'months', and any response-size behavior are 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% for the single 'months' parameter, so the baseline is 3, but the description adds a genuine semantic tie-in: fewer than 6 months of history degrades forecast confidence to 'rough'. That is meaningfully more than the schema's bare 'How many months of history to include'.

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

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

The opening sentence gives a specific verb and resource ('Returns the user's monthly net-worth history plus a linear forecast') and even specifies the forecast horizons, so an agent immediately knows the scope. It implicitly differs from the snapshot-style sibling get_net_worth, but no sibling is ever named, so the differentiation is left to inference.

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

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

The description is heavy on how to *present* results (respect the setting, give counterfactuals, don't imply no property), but never says when to call this tool versus get_net_worth, project_retirement, simulate_scenario, or get_wealth_percentile. Usage selection is only implied by the tool's content.

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

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

With annotations already covering read-only, idempotent, and non-destructive semantics, the description goes well beyond them: it discloses that values are estimates, that currencies are converted to base, that category nesting is capped at depth 2, how savings is computed, and precisely how to interpret and relay an 'empty: true' result instead of treating it as an error.

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

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

The core purpose is front-loaded in the first clause and every subsequent sentence carries distinct information (contents, planning-vs-actual caveat, empty-state handling). It is somewhat long and leans on capitalized emphasis to restate the same warning, which costs a little density.

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

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

No output schema exists, so the description carries the burden of describing the return payload, and it does so thoroughly (field list, currency normalization, nesting depth, derived total and savings) plus the edge case of missing data. An agent has everything needed to call and interpret it.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the baseline for 0-param tools this is a 4. The description correctly adds no pointless parameter discussion.

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 ('Returns the authenticated user's monthly BUDGET PLAN') and then enumerates exactly what is returned: income, category tree (max depth 2), estimated costs with currency conversion, totals, and potential savings. It explicitly contrasts itself with spending views ('do NOT reflect actual spending'), which is the key distinction from sibling tools like get_accounts or get_net_worth.

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 framing as a 'PLANNING view' versus actual spending gives clear context for when the tool's output is appropriate, and it prescribes handling of the empty-result case (relay message and next_step_url). It stops short of naming which sibling tool to call instead when the user wants actual spend, so routing between siblings is left partly 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, and the description goes well beyond them: it discloses that property_equity is always present and may be negative, that property_equity_counted_in_net_worth and include_property_in_net_worth explain the inclusion decision, and that empty:true means missing user data with a next_step_url rather than an error. This 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?

Purpose is front-loaded in the first clause and the field/behavioral notes are ordered logically. It is on the long side and several presentation-policy sentences could be tightened, but each carries behavioral weight rather than restating the schema.

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

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

With no output schema and only one input parameter, the description correctly carries the return-value burden — naming the response fields, the property-inclusion flags, and the empty-result shape. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100% and it is a single optional parameter, so the baseline is 3. The description earns an extra point by explaining what month actually does semantically — it 'overrides the snapshot month' — which the schema's bare 'YYYY-MM, optional' does not convey.

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

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

States a precise verb and resource ('Returns the authenticated user's current net worth in their base currency') and enumerates the category breakdown, so the scope is unambiguous. It does not explicitly name or distinguish itself from siblings like get_accounts or get_balance_history, which is the only thing keeping 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?

The description is rich in guidance, but almost all of it concerns how to present and interpret results (respect the setting, give the counterfactual, don't imply no property) rather than when to choose this tool over alternatives. Tool selection relative to get_accounts / get_balance_history / get_wealth_percentile is left entirely implicit.

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 the description adds substantial non-obvious behavior: balances are never converted between currencies, the positive/negative sign convention, that only friend names are exposed (never emails or avatars), and the empty-result contract. These are exactly the traits an agent cannot get from the annotations.

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

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

Front-loaded with the core purpose, then each following clause carries distinct payload: currency rule, sign semantics, privacy constraint, and empty-result handling. No filler or restated title 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 output schema, the description carries the return-shape burden and does so thoroughly — itemizing contents, explaining the sign convention, the per-currency scope, and the empty-response path. Nothing an agent needs to call and interpret this tool 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 per the rubric the baseline is 4. The description adds nothing parameter-related because there is nothing to add — the ledger shape is described instead.

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

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

The description states a specific verb and resource — 'Returns the authenticated user's Splits ledger' — and enumerates the exact contents (per-friend balances per currency, totals, groups, 20 recent expenses). That scope distinguishes it from the sibling aggregate tools (get_net_worth, get_budget, get_balance_history) without needing to name them, though no explicit sibling contrast is drawn.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for split/shared-expense balances. The empty:true handling is a genuine operational guideline (relay message and next_step_url instead of erroring). But there is no explicit when-to-use versus alternatives, nor prerequisites.

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 this a safe, idempotent, non-open-world read, so the safety profile is covered. The description adds genuine value beyond that by enumerating the returned elements and by disclosing the empty:true sentinel and how to handle it — a non-obvious behavioral contract that prevents the agent from misreporting missing data as an error.

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

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

Two sentences, no filler, with the core purpose front-loaded and the edge-case handling second. Every clause carries information an agent needs.

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 and zero required parameters, the description does the necessary work of naming the return fields and the empty-result path. It could go slightly further on how the month parameter affects the percentile window, but nothing essential is missing for a correct call.

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

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

Schema description coverage is 100% for both parameters, so the schema already carries the syntax. The description adds only the default behavior for compare_country (falls back to the saved compare-country) and says nothing about how month interacts with the result or what happens on an invalid country code, 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 (returns the user's net-worth percentile) plus the two scoping dimensions that define it: age band and country. This cleanly separates it from the raw-value sibling get_net_worth without needing to name it.

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 guidance for the empty-result branch (relay message and next_step_url rather than treat as an error), which is real usage direction. However it never says when to prefer this over get_net_worth or project_retirement, so the tool-selection decision is left 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds real context beyond them: the default retirement age of 65, how saving is inferred, the low/mid/high + confidence return shape, a 'not financial advice' caveat, and a non-error empty-state contract pointing to message and next_step_url. That empty-state handling is a meaningful behavioral disclosure an agent would otherwise get wrong.

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

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

Four sentences, none wasted, with the purpose front-loaded and the operational empty-state rule placed last as the actionable caveat. Dense but appropriately sized for a tool with a nested-parameter schema and 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?

With no output schema, the description usefully summarizes the return shape and the empty-result contract, and no annotations are contradicted. The remaining gap is parameter documentation, particularly the growth_rates object and the month key, which an agent would have to guess at.

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 0% for four parameters, so the description must compensate. It partially does: retirement_age's default (65) and monthly_saving's history-inferred nature are explained, but 'month' and the low/mid/high growth_rates object are left entirely undocumented in both places, leaving two parameters opaque.

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 the user's net worth at retirement age') plus the computation basis (future-value maths, history-inferred saving), which cleanly separates it from siblings like get_net_worth and simulate_scenario. An agent can identify the tool without opening the schema.

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

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

Implied usage is clear (retirement-age net worth projection) and the empty-result branch gives concrete operational guidance, but the description never says when to prefer this over simulate_scenario or get_net_worth. No explicit alternatives or exclusions are named.

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, closed-world), so the bar is lower. The description still adds real context beyond them: it discloses the return shape (baseline vs scenario at low/mid/high) and the empty-state contract with next_step_url, neither of which is derivable from 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 purpose, then scenario types, then return shape, then the edge case — a logical order with dense, low-waste sentences. The 'Not financial advice' disclaimer is arguably filler but is defensible for a finance tool.

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

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

For a nested, six-parameter tool with 0% schema coverage and no output schema, the description covers purpose, scenario-type semantics, return structure, and the empty-result contract. The main remaining gap is the undocumented top-level parameters (month, horizon_years, monthly_saving, retirement_age).

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 0% and the nested 'params' object is opaque (additionalProperties: {}), so the description carries the full burden. It rescues this by mapping each scenario type to its expected keys (delta_monthly, amount, low/mid/high, target_amount/by_year), but leaves the top-level month, horizon_years, monthly_saving and retirement_age params undocumented.

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 ('Simulates a what-if scenario against the user's projected net worth') and enumerates the four supported scenario types, which makes the tool's scope unambiguous. It does not explicitly name or contrast with the closely related sibling 'project_retirement', so sibling differentiation is left implicit.

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 the tool's name and purpose rather than stated: nothing tells the agent when to pick this over project_retirement or get_net_worth. The one piece of explicit guidance is handling of the 'empty: true' result (relay message and next_step_url rather than treat as error), which is useful but narrow.

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