Demo personal-finance MCP App: spending, subscriptions, and net worth as interactive UI.
Scored across 9 tools
Each tool targets a distinct insight (net worth, spending, subscriptions, transactions) with a clear compute-vs-render split, and descriptions explicitly warn which to pick (e.g. transaction_list vs trend_card). However the near-identical get_X / X pairs (get_net_worth vs net_worth_trend, get_spending_breakdown vs spending_breakdown) risk misselection since the only differentiator is 'numbers to reason with' vs 'to display'.
Compute tools follow a clean get_noun pattern, but the render tools use three different conventions: net_worth_trend/trend_card (noun_trend), spending_breakdown/subscriptions (bare nouns), and transaction_list (noun_list). The dots don't line up between the compute and render halves, making the pairing non-obvious.
Nine tools is well within the sweet spot and each earns its place: four compute tools, four dedicated render cards, and one generic trend_card for metrics without a dedicated card. Nothing feels padded or missing.
The surface covers the core read/insight domain well — net worth, spending, subscriptions, transactions, and trends over time. It's read-only so the lack of budgets, income breakdown, or account/transfer operations is a modest gap an agent can work around.
Net worth history + account balances. Numbers to reason with — to display, use net_worth_trend.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | How far back the trend goes. Ignored when startDate/endDate are given. | 1y |
| endDate | No | Range end, YYYY-MM-DD. Defaults to today. | |
| groupBy | No | Granularity of the returned series. Each point carries that period's CLOSING balance. 'auto' picks a readable granularity for the span; set it explicitly to compare periods against each other — 'year' over a two-year range gives one point per year, 'month' gives one per month. | auto |
| summary | No | Omit the `points` series and return only the headline figures and accounts. Use this when you want the numbers to comment on rather than to chart — it is a fraction of the size of a full result. | |
| startDate | No | Range start, YYYY-MM-DD. Defaults to a year before endDate. |
| Name | Required | Description |
|---|---|---|
| saved | No | |
| start | No | |
| change | No | |
| income | No | |
| period | No | |
| points | No | |
| current | No | |
| endDate | No | |
| groupBy | No | |
| accounts | No | |
| spending | No | |
| startDate | No | |
| change_pct | No | |
| periodLabel | No |
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 covered. The description adds the useful distinction that output is numeric/analytical rather than presentational, but discloses nothing about pagination, result size beyond the summary hint, or account scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with zero filler; the purpose is front-loaded and the alternative follows. Every clause carries 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 a full output schema, complete parameter docs, and annotations covering the safety profile, the description only needs to establish purpose and routing, which it does. It leaves minor gaps around which accounts are included in the balances, but nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema itself explains period, groupBy granularity/closing-balance semantics, summary, and date precedence. The description adds no parameter meaning beyond that, so the 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 resource and scope: net worth history plus account balances. It also explicitly differentiates itself from the sibling net_worth_trend, so an agent can distinguish the two 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?
Names the alternative (net_worth_trend) and the exact condition that selects it: use this tool for numbers to reason with, use the sibling for display. This is explicit when-to-use/when-not guidance rather than an implied use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Categorized spending + prior-period comparison. Numbers to reason with — to display, use spending_breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | Spending window. | mtd |
| summary | No | Drop each category's top_merchants list and return only the headline totals and per-category amounts. Use this when you want the numbers to comment on rather than to chart. |
| Name | Required | Description |
|---|---|---|
| net | No | |
| groups | No | |
| period | No | |
| comparison | No | |
| periodLabel | No | |
| total_spend | No | |
| total_income | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered by structured data. The description adds genuine behavioral context beyond that: the result includes a prior-period comparison, and the output is intended for reasoning rather than rendering. It stops short of return-format or pagination detail, but with output schema present that gap is minor.
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 with zero filler; the scope statement comes first and the routing hint second. 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 an output schema carrying return values and full schema coverage on parameters, the description only needs to establish purpose and routing, which it does. It is nearly complete, though it could have noted the default window behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (period, summary) are already documented with defaults and the enum list. The description adds nothing about either parameter, so the 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 resource (categorized spending) plus a distinguishing capability (prior-period comparison), and explicitly distinguishes itself from the sibling spending_breakdown. An agent can tell the two 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?
'Numbers to reason with — to display, use spending_breakdown' names the alternative and the exact condition that routes to it. This mirrors the ideal pattern of stating when this tool is correct and when the sibling is.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recurring-charge detection. Numbers to reason with — to display, use the subscriptions card.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Which subscriptions to include. | active |
| Name | Required | Description |
|---|---|---|
| count | No | |
| new_count | No | |
| subscriptions | No | |
| total_monthly | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint=false, so the safety profile is covered. The description adds only the notion that results are raw 'numbers to reason with' rather than presentational, with no detail on scope, freshness, or coverage.
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 clauses, purpose front-loaded before the display caveat, with no filler. It is arguably under-specified rather than padded, so conciseness is good but not exemplary.
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 an output schema present and a 100%-covered single-parameter input, the description needn't explain returns or params. It adequately covers purpose and the display alternative, leaving only minor gaps about scope of detection.
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 single 'status' enum is self-explanatory with a default. The description adds nothing about what 'active' versus 'all' means, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The phrase 'Recurring-charge detection' states what the tool produces, and combined with the name get_subscriptions the verb+resource is clear. It also implicitly separates itself from the display-oriented sibling ('subscriptions' card), though it does not name the other data 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 an explicit when-not and alternative: for display, use the subscriptions card rather than this tool. That routing is valuable, but it offers no guidance relative to the other data siblings like get_spending_breakdown or get_transactions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Raw transactions by category or merchant, ~12 months of history. Numbers to reason with — to display, use transaction_list.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | 'recent' is newest-first and is what a plain list wants. Use 'largest' for "my biggest transactions" — a window can hold hundreds of rows, so date order buries them. | recent |
| limit | No | Max transactions to return. Pass 0 for totals and counts only — much cheaper when you need the figures to reason with rather than to list. | |
| period | No | Time window. Ignored when startDate/endDate are given. The feed covers ~25 months, so a 1y window has a full prior year to compare against. | mtd |
| endDate | No | Window end, YYYY-MM-DD. Defaults to today. | |
| category | No | Category or plain term to filter by, e.g. 'Food & Dining', 'restaurants', 'rent', 'gas', 'income'. A merchant name here is resolved as a merchant. Omit or leave empty for all categories. | |
| merchant | No | Single store or brand to filter by, e.g. 'Whole Foods', 'Netflix', 'Shell'. Combine with category to narrow further. | |
| startDate | No | Window start, YYYY-MM-DD. Defaults to 30 days before endDate. |
| Name | Required | Description |
|---|---|---|
| count | No | |
| shown | No | |
| category | No | |
| standouts | No | |
| top_items | No | |
| periodLabel | No | |
| total_spent | No | |
| transactions | No | |
| change_vs_prev_pct | No |
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 structurally; the description adds that results are 'raw' and roughly a year deep. However it states '~12 months of history' while the period parameter says the feed covers ~25 months, an internal inconsistency that muddies the scope claim. No mention of row counts, cost, or pagination beyond what the schema already says.
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 resource and scope, then the routing rule. No filler, and the contrastive 'to display, use transaction_list' clause earns its place by preventing a wrong tool choice.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a rich schema and an output schema, so return-value detail is not needed here. The only real gap is the '~12 months' vs '~25 months' discrepancy, which leaves the agent unsure how far back results actually go.
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 period/limit/sort parameters are already richly documented in the schema (including the limit=0 totals trick and the startDate/endDate override). The description repeats category/merchant in prose but adds no new syntax or default behavior, so the 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 ('Raw transactions') plus the filter axes (by category or merchant) and the historical scope (~12 months), and explicitly contrasts itself with the sibling transaction_list. An agent can select it over transaction_list 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 a clear use condition ('Numbers to reason with') and names the alternative for the other case ('to display, use transaction_list'). That routing is explicit, but there is no guidance on when neither applies or on the sort/period choices, so it stops short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render net_worth_trend: Net worth: current total, change over the period, a trend chart, and the account balances behind it. It loads its own data. To compare periods against each other pass chartStyle:'bar' plus groupBy ('year' for this-year-vs-last-year, 'month' for month-by-month) — each bar is that period's closing balance.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Usually omit this. Optional one-line insight rendered inside the card. Only pass it when you ALREADY have the figures in hand from a call you made for another reason — never make an extra tool call just to write a note, because that round trip delays the card itself. When you do add one, say something the card does not already show (what drove a change, what to watch), in one sentence, and never guess a number. | |
| period | No | Window: 7d, 30d, mtd (this month so far), lastMonth (the whole previous calendar month), 3mo, 6mo, ytd, 1y or all. Ignored when startDate/endDate are given. Defaults to 1y. | |
| endDate | No | ||
| groupBy | No | One bar/point per period, carrying that period's closing balance. Set it to compare periods: 'year' for "this year vs last year", 'month' for "month by month", 'quarter' for "by quarter". Leave auto for a plain trend. | auto |
| nextSteps | No | One short follow-up the user might ask next, in the form icon|question — 'calendar|Show me last month'. Phrase the question the way the user would say it, and take the icon from the table in the app instructions; any other name renders blank. Always supply 2-3. The card itself ignores them. | |
| startDate | No | ||
| chartStyle | No | 'bar' compares periods against each other as closing balances; 'line' is the continuous history. | line |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the tool self-loads its data (no prerequisite fetch call needed) and how bar/groupBy interact to change what each datum represents (a period's closing balance). No rate limits, pagination, or auth details, but the added self-loading fact is meaningful.
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 what the card shows before moving to the comparison configuration. The second sentence is long and dense with parenthetical examples, but every clause carries usable information and nothing is redundant.
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 describing the return payload (total, period change, chart, underlying balances), which is what an agent needs to know before calling. The gaps — startDate/endDate semantics and any differentiation from get_net_worth — are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 71%, so the schema carries most param documentation (period, note, groupBy, chartStyle all described inline). The description adds a combination rule the schema cannot express on its own: chartStyle:'bar' must be paired with groupBy, and each bar then represents that period's closing balance. It leaves startDate/endDate entirely unexplained beyond the period note that they override the window.
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 (render) and resource (net worth trend) and enumerates the card contents: current total, change over period, trend chart, account balances. It also notes 'It loads its own data,' which hints at why it exists separately from the raw get_net_worth sibling, but it never names that sibling or trend_card 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 concrete configuration guidance for the comparison use case ('pass chartStyle:bar plus groupBy — year for this-year-vs-last-year, month for month-by-month') and implies the default line/auto case is a plain trend. However, it never says when to choose this tool over the sibling get_net_worth or trace_card, so usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render spending_breakdown: Spending split by category for a period: a composition bar plus a ranked category list. It loads its own data — pass the period alone for the whole picture, which is what a broad 'where did my money go' question wants. Use highlight only on a follow-up about particular categories; it dims everything else, so on an opening question it hides most of the answer.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Usually omit this. Optional one-line insight rendered inside the card. Only pass it when you ALREADY have the figures in hand from a call you made for another reason — never make an extra tool call just to write a note, because that round trip delays the card itself. When you do add one, say something the card does not already show (what drove a change, what to watch), in one sentence, and never guess a number. | |
| period | No | Window: 7d, 30d, mtd (this month so far), lastMonth (the whole previous calendar month), 3mo, 6mo, ytd, 1y or all. | mtd |
| highlight | No | OMIT THIS unless the user asked about specific categories. Leaving it empty is the normal, correct view: the whole picture, nothing dimmed. A broad opening question — 'where did my money go', 'show me my spending', 'how did I do this month' — wants the whole picture, so pass period alone. Only emphasise on a FOLLOW-UP that is genuinely about particular categories ('what should I cut', 'is dining out of hand', 'why is it higher than last month'), where you name them: ['Food & Dining','Subscriptions']. Everything else then dims and the hero reports their combined total. Matching is forgiving ('dining' finds 'Food & Dining'). | |
| nextSteps | No | One short follow-up the user might ask next, in the form icon|question — 'calendar|Show me last month'. Phrase the question the way the user would say it, and take the icon from the table in the app instructions; any other name renders blank. Always supply 2-3. The card itself ignores them. | |
| drillPrompt | No | What tapping a category should ask, when the question had an angle worth carrying. Write it as the user would say it and put {category} where the name goes: 'Show me the odd {category} transactions', 'Where can I cut back on {category}?'. Set it when the card answers something pointed — unusual spending, what to cut, why something moved — so the follow-up inherits that instead of resetting to a plain list. Omit it for a broad 'where did my money go', where a plain list is what a tap should give. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond that: the card self-loads its data (no prior fetch needed) and that highlight dims all non-selected categories, a side effect the annotations cannot express.
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 operation and output shape, then the usage constraint. Mostly waste-free, with only minor redundancy where the 'broad where did my money go' example is echoed between the description body and the highlight constraint.
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 states what renders (composition bar + ranked list) and the highlight dimming behavior. It is complete enough for an agent to call it correctly; only the sibling-relationship to get_spending_breakdown is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds the interaction semantics between period and highlight (period alone = full picture; highlight suppresses everything else) that the schema does not convey. note, nextSteps and drillPrompt are left entirely to their schema 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?
States a specific verb ('Render') plus the resource and its composition ('Spending split by category... a composition bar plus a ranked category list'). The phrase 'It loads its own data' implicitly distinguishes it from the data-fetching sibling get_spending_breakdown, though it never names that sibling 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?
Explicitly says to pass period alone for the whole picture, and restricts highlight to follow-up questions about particular categories, with a clear when-not ('on an opening question it hides most of the answer'). This is exactly the selection guidance an agent needs versus the data siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render subscriptions: Recurring charges: total monthly cost and a row per subscription with its cadence, next charge date, and New / price-increase flags. It loads its own data.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Usually omit this. Optional one-line insight rendered inside the card. Only pass it when you ALREADY have the figures in hand from a call you made for another reason — never make an extra tool call just to write a note, because that round trip delays the card itself. When you do add one, say something the card does not already show (what drove a change, what to watch), in one sentence, and never guess a number. | |
| view | No | Which cut to open on. 'all' is every recurring charge, biggest first — the answer to 'what am I paying for'. 'repriced' is only the ones whose price moved, which is what 'which went up' asks. 'new' is only the recently started. 'unusual' is both of those together, for a general 'anything odd'. Match the cut to the question: a price question answered with the full list makes the user hunt for the answer. The header keeps reporting the full count, so narrowing hides nothing. | all |
| views | No | Which cuts to offer as segments. Omit and the card offers All alongside whichever cut you opened on. Pair the specific cut with 'all' so the user can get back to the full picture — ['all','repriced'] for a price question, ['all','new'] for a what's-new one. | |
| status | No | 'active' lists current subscriptions; 'all' also includes recently cancelled ones. | active |
| nextSteps | No | One short follow-up the user might ask next, in the form icon|question — 'calendar|Show me last month'. Phrase the question the way the user would say it, and take the icon from the table in the app instructions; any other name renders blank. Always supply 2-3. The card itself ignores them. |
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 covered. The description adds one genuine behavioral fact — 'It loads its own data' — which tells the agent no prerequisite fetch is needed, but nothing about latency, caching, or the note/view rendering side effects.
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 purpose before the content breakdown, with no filler. The double colon in 'Render subscriptions: Recurring charges:' is slightly awkward but harmless.
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 self-loading render card with no output schema, the description covers what will be displayed and notes that it fetches its own data, which is the key operational fact. It omits how the rendered result is returned and whether any interaction/round-trip is expected.
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 every one of the five parameters carries a rich, detailed description (including the note-avoidance rule and view/views pairing rationale), so the schema already does the heavy lifting. The tool description contributes nothing about parameters, which is the correct baseline of 3 when coverage is full.
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 ('Render') and resource ('subscriptions') and enumerates the card's contents (monthly total, cadence, next charge, New/price-increase flags). It is clear what the tool produces, though it never names or contrasts with the sibling get_subscriptions, leaving the render-vs-fetch distinction 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 only implied: it is a render tool, so an agent infers 'call this to show the subscriptions card'. There is no explicit when-to-use, no when-not, and no routing guidance distinguishing it from get_subscriptions or the other card tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render transaction_list: Individual purchases for a category or a merchant: the window total plus the matching transactions. It loads its own data. Plain terms like 'restaurants', 'groceries' or 'gas' resolve to categories; omit both filters for all spending. Do NOT use this when the user asks how much they spent over the last 3, 6 or 12 months — that is a period comparison, so use trend_card with chartStyle:'bar' instead.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Usually omit this. Optional one-line insight rendered inside the card. Only pass it when you ALREADY have the figures in hand from a call you made for another reason — never make an extra tool call just to write a note, because that round trip delays the card itself. When you do add one, say something the card does not already show (what drove a change, what to watch), in one sentence, and never guess a number. | |
| view | No | Which cut of the window to open on. 'recent' is newest-first, the plain list. 'largest' leads with the biggest charges. 'unusual' shows only the charges well above what that merchant or category normally costs — this is the answer to "anything odd this month", not a spending breakdown. The user can switch between the offered cuts on the card without asking again, so pick the one that answers the question and leave the rest to them. Use `views` to change which cuts are offered. | recent |
| limit | No | Max transactions to load. Raise past the default 20 only if the user wants the full list. | |
| views | No | Which cuts to offer as segments on the card. Omit for all three, which is usually right — the user can then explore without asking again. Narrow it only when a cut would be meaningless for what was asked: a single-merchant list has little to call unusual, and a one-week window has little to rank. Listing a single cut drops the control entirely and renders a plain list, so use that when the question has exactly one sensible answer. | |
| period | No | Window: 7d, 30d, mtd (this month so far), lastMonth (the whole previous calendar month), 3mo, 6mo, ytd, 1y or all. Ignored when startDate/endDate are given. Defaults to mtd. | |
| endDate | No | Window end, YYYY-MM-DD. | |
| category | No | Category or plain term, e.g. 'Food & Dining', 'restaurants', 'rent', 'gas'. Omit for all categories. | |
| merchant | No | Single store or brand, e.g. 'Whole Foods', 'Netflix'. | |
| nextSteps | No | One short follow-up the user might ask next, in the form icon|question — 'calendar|Show me last month'. Phrase the question the way the user would say it, and take the icon from the table in the app instructions; any other name renders blank. Always supply 2-3. The card itself ignores them. | |
| startDate | No | Window start, YYYY-MM-DD. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds genuinely new behavior — that the card loads its own data and that the user can switch offered cuts without re-asking. It does not cover return shape or pagination, but for a read-only listing tool this is solid added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with what it renders before the exclusion. The 'Render transaction_list:' prefix is mildly redundant with the tool name, but nothing else is wasted and the routing rule comes before the caveat.
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 10 optional parameters, 100% schema coverage, and no output schema, the description covers the key gaps an agent needs: default window, the 20-item default limit, how cuts render, and the trend_card escape hatch. Only the get_transactions-vs-transaction_list boundary is left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema lacks: plain terms like 'restaurants'/'gas' resolve to categories, and omitting BOTH filters means all spending. That interaction between category and merchant is not stated in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Render transaction_list: Individual purchases for a category or a merchant: the window total plus the matching transactions.' It explicitly separates itself from trend_card, but it never distinguishes itself from the similarly named sibling get_transactions, leaving a real ambiguity unaddressed.
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 conditions (filter by category or merchant; omit both for all spending) and an explicit when-not with the named alternative — multi-month total questions must use trend_card with chartStyle:'bar'. Both the routing and the exclusion are stated, not implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render trend_card: Any metric over time that has no dedicated card — one category's spend by month, a series you computed. Points are {label, value} in display order. Set upIsGood=false for cost-like metrics. Use chartStyle:'bar' whenever the user compares periods — month by month, or over the last 3/6/12 months; give each point a series name (repeating the label once per series) to stack them with a legend. Pass items to list the composition behind the number.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Usually omit this. Optional one-line insight rendered inside the card. Only pass it when you ALREADY have the figures in hand from a call you made for another reason — never make an extra tool call just to write a note, because that round trip delays the card itself. When you do add one, say something the card does not already show (what drove a change, what to watch), in one sentence, and never guess a number. | |
| items | No | Optional rows under the chart — the composition behind the number (accounts behind a net worth, categories behind a month's spend). Each is { name, detail, value, color?, prompts? }. `color` is a named colour for the dot ('blue', 'green', …); omit it and rows are coloured in order. `prompts` are follow-up questions offered when the row is tapped — each string is shown as the menu label AND sent to the assistant verbatim, so keep them short and self-contained ('How has my Brokerage changed?', not 'changed?'). OMIT `prompts` unless a row needs something its name cannot imply: left out, the card builds its own drill-down from `name`, which saves you writing the same sentence once per row. | |
| start | No | ||
| title | No | Trend | |
| change | No | The change over the period, in the same unit as `current`. Send it together with `start` whenever you have them: the card leads with this figure, and left out it has to work back from `change_pct`, which is close but not the real number. | |
| points | No | ||
| current | No | ||
| upIsGood | No | false for cost-like metrics: an increase renders red, a decrease green. | |
| nextSteps | No | One short follow-up the user might ask next, in the form icon|question — 'calendar|Show me last month'. Phrase the question the way the user would say it, and take the icon from the table in the app instructions; any other name renders blank. Always supply 2-3. The card itself ignores them. | |
| change_pct | No | ||
| chartStyle | No | 'bar' draws discrete bars on a labelled x axis — better for comparing periods against each other, and the only style that stacks series. 'line' is the continuous trend. | line |
| periodLabel | No | Past 12 months | |
| valueFormat | No | How the hero value and change are formatted. | currency |
| valueSuffix | No | Optional unit appended to values, e.g. ' subs' or '/mo'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe read-only, idempotent, non-destructive profile, so the description is free to add rendering behavior — points/items composition, the bar-stacking-with-legend behavior when a `series` is repeated, and the metric-direction color semantics. It goes beyond the annotations, though it doesn't describe period/pagination or how the card is surfaced back to the agent.
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 dense sentences, front-loaded with scope then the chart-style rule then composition, with no filler. The 'Render trend_card:' opener is mildly redundant with the name, but the rest is tightly written.
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 14-parameter, no-output-schema rendering tool this covers the essentials an agent needs — scope, direction-of-good, chart style, series stacking, composition rows. It leaves minor gaps (periodLabel/valueFormat interplay, title), but the parameter-level schema descriptions here are unusually rich and fill most of those.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 57% and several parameters (points, series, start, current, periodLabel, change_pct) have no schema descriptions, so the description has to compensate — and it does, explaining points as '{label, value} in display order', the `series` stacking convention, and upIsGood direction. It adds real meaning beyond the schema but doesn't cover every undocumented field.
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 (Render) and resource (trend_card) and immediately scopes it to 'Any metric over time that has no dedicated card', with concrete examples ('one category's spend by month, a series you computed'). That 'no dedicated card' clause implicitly routes the agent away from siblings like net_worth_trend and spending_breakdown, so the tool is distinguishable 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?
It provides clear conditional rules: 'Set upIsGood=false for cost-like metrics', and 'Use chartStyle:bar whenever the user compares periods — month by month, or over the last 3/6/12 months'. The 'no dedicated card' framing is the when-to-use gate and implies when-not (use the dedicated card instead), though no sibling is named explicitly as the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_net_worthget_spending_breakdownget_subscriptionsget_transactionsnet_worth_trendspending_breakdownsubscriptionstransaction_listtrend_cardQuery your real net worth, spending, transactions, budgets and portfolio from any MCP client.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Public read-only Précis Finance MCP demo with synthetic data; no account or credentials required.
SmartMoney77 MCP v0.6.0 — 14 public tools that turn financial questions into exact numbers and citable links. New: historical_investment_return and compare_investments, which compute "what if I had invested" results from real yearly price data. Also compound interest, FIRE number, credit-card payoff, emergency fund, inflation, latte factor, investment fees, cost of waiting, plus discovery/deep-link/share-pack tools for a catalog of calculators in 6 languages (he/en/ar/es/pt/in). Public, no login. Endpoint: https://smartmoney77.com/mcp
Add one secure layer between your agents and this server.
