This server lets an AI assistant read and update your Monarch Money finances through MCP, including accounts, transactions, budgets, cashflow, and spending analysis.
Accounts: list accounts, view balances, holdings, balance history, linked institutions, create manual accounts, and trigger data refreshes
Transactions: fetch with filters (dates, accounts, categories, tags, recurring, splits, attachments, review status), search by merchant/keyword, create manual transactions, update single or bulk transactions, and manage transaction splits
Budgets & cashflow: get budgets, set budget category amounts, and analyze cashflow income/expenses
Recurring transactions: view scheduled occurrences and update merchant-wide recurring schedules
Spending insights: get spending summaries grouped by category/account/month, multi-month trend analysis with forecasting, and a one-call complete financial overview
Convenience: compact or verbose output formats, natural-language dates, MCP resources/prompts, and parallel bulk operations
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Monarch Money MCP Server show my recent transactions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Use an AI assistant to read and update your Monarch Money accounts, transactions, and budgets through MCP.
This FastMCP rewrite adds these tools to colvint's original server:
Search and bulk edits: search_transactions finds merchants or keywords; update_transactions_bulk edits transactions in parallel with per-item results.
Spending analysis: get_spending_summary groups totals by category, account, or month; analyze_spending_patterns compares months.
One-call overview: get_complete_financial_overview combines accounts, budgets, cashflow, transactions, and categories.
Splits and recurring schedules: read and replace transaction splits, view scheduled occurrences, and edit merchant-wide recurrence. Recurring date filters and editing are unreleased.
Unlike the original and keithah's enhanced Python fork, this server also provides:
Typed results: structured output with outputSchema, plus a text fallback.
MCP resources and prompts: account/category/institution resources, per-account holdings/history templates, and guided prompts with argument completion.
Assistant-friendly calls: compact transaction/category records, natural-language dates, read/write labels, and progress on batch analysis.
Comparison checked September 14, 2026. Other forks overlap on financial tools; the enhanced Python fork exposes a broader library API. This project focuses on analysis workflows and MCP integration, not exposing every API method. See the tool catalog.
Related MCP server: Lunch Money MCP Server
Install uv, then configure your MCP client to run uvx monarch-mcp-jamiew. You'll need your Monarch email and password, plus an MFA secret for TOTP-based 2FA.
Release status: This README covers source. Recurring date filters and editing, stricter bulk validation, and the latest authentication fixes are unreleased. Use source setup for these; uvx runs the published release.
For clients with an mcpServers config:
{
"mcpServers": {
"monarch-money": {
"command": "uvx",
"args": ["monarch-mcp-jamiew"],
"env": {
"MONARCH_EMAIL": "your-email@example.com",
"MONARCH_PASSWORD": "your-password",
"MONARCH_MFA_SECRET": "your-mfa-secret-key"
}
}
}
}Add the monarch-money entry from the standard config to your config file's mcpServers object (create the file if needed):
macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Then fully quit and reopen Claude Desktop.
claude mcp add monarch-money \
-e MONARCH_EMAIL=your-email@example.com \
-e MONARCH_PASSWORD=your-password \
-e MONARCH_MFA_SECRET=your-mfa-secret-key \
-- uvx monarch-mcp-jamiewAdd -s user to make it available across all your projects. Verify with claude mcp list.
codex mcp add monarch-money \
--env MONARCH_EMAIL=your-email@example.com \
--env MONARCH_PASSWORD=your-password \
--env MONARCH_MFA_SECRET=your-mfa-secret-key \
-- uvx monarch-mcp-jamiewOr add the equivalent block to ~/.codex/config.toml:
[mcp_servers.monarch-money]
command = "uvx"
args = ["monarch-mcp-jamiew"]
env = { MONARCH_EMAIL = "your-email@example.com", MONARCH_PASSWORD = "your-password", MONARCH_MFA_SECRET = "your-mfa-secret-key" }For Claude Code's project scope, save the standard config as .mcp.json in your project root. Keep credential-bearing files out of version control.
Add to ~/.hermes/config.yaml under mcp_servers:, then /reload-mcp (or restart Hermes):
mcp_servers:
monarch-money:
command: uvx
args: ["monarch-mcp-jamiew"]
env:
MONARCH_EMAIL: "your-email@example.com"
MONARCH_PASSWORD: "your-password"
MONARCH_MFA_SECRET: "your-mfa-secret-key"Add the standard config to ~/.openclaw/openclaw.json under mcpServers, then restart the gateway.
Set up a local stdio MCP server with command uvx, argument monarch-mcp-jamiew, and the credentials above. Follow your client's config format.
Not sure how? Tell your agent:
Install the Monarch Money MCP server from https://github.com/jamiew/monarch-mcp. The PyPI package is
monarch-mcp-jamiew, run viauvx monarch-mcp-jamiew. It needsMONARCH_EMAIL,MONARCH_PASSWORD, andMONARCH_MFA_SECRETfor TOTP-based 2FA.
Source installs use a pinned monarchmoneycommunity commit:
git clone https://github.com/jamiew/monarch-mcp
cd monarch-mcp
uv sync --lockedThen point your client at the local copy with absolute paths (find them with which uv and pwd):
{
"mcpServers": {
"monarch-money": {
"command": "/abs/path/to/uv",
"args": ["--directory", "/abs/path/to/monarch-mcp", "run", "python", "server.py"],
"env": {
"MONARCH_EMAIL": "your-email@example.com",
"MONARCH_PASSWORD": "your-password",
"MONARCH_MFA_SECRET": "your-mfa-secret-key"
}
}
}
}Theclaude mcp add and codex mcp add commands can save credentials in shell history. Edit the client's config directly to avoid that, and protect the config file.
Go to Monarch Money settings and enable 2FA
When shown the QR code, look for "Can't scan?" or "Enter manually"
Copy the TOTP secret key, not the rotating six-digit code
Use this as your MONARCH_MFA_SECRET
The source checkout exposes these 22 tools. See release status for unpublished changes.
Tool | Description |
| List accounts with balances |
| Transactions with date/account/category filtering |
| Search by merchant name or keyword |
| Category list (compact by default) |
| Create a manual transaction |
| Update a single transaction |
| Update multiple transactions in parallel |
| Read a transaction's splits |
| Replace all splits; an empty list removes them |
| Budget data and spending analysis |
| Income and expense analysis |
| Investment holdings for an account (requires |
| Account balance history |
| Linked financial institutions |
| Scheduled occurrences within a date range |
| Change a merchant's recurring schedule |
| Set a budget category amount |
| Create a manually tracked account |
| Trigger account data refresh |
| Spending aggregated by category, account, or month |
| Combine accounts, budgets, cashflow, transactions, and categories |
| Multi-month trend analysis |
get_recurring_transactions(start_date, end_date) returns a forecast, not posted history.
Dates accept ISO or natural language. No dates selects this month; one date fills
the missing bound from that month.
Occurrences include stream, account, category, and a matched transactionId when
available. isPast does not mean paid. Use get_transactions(is_recurring=True)
for recorded transactions; do not count forecasts and posted matches twice.
update_recurring_transaction changes a merchant-wide schedule, not one occurrence.
Use stream.merchant.id, not stream.id or transactionId, and the current merchant
name to avoid renaming it. Pass only settings to change: frequency, base_date,
amount, is_recurring, or is_active. Omitted settings stay unchanged.
Use Monarch's frequency and signed amount. This does not cancel subscriptions,
move money, or create posted transactions.
get_transactions and search_transactions return compact records by default:
{
"id": "txn_123",
"date": "2025-03-15",
"amount": -12.50,
"merchant": "Corner Deli",
"plaidName": "CORNER DELI NYC",
"category": "Restaurants & Bars",
"categoryId": "cat_001",
"account": "Main Credit Card",
"needsReview": true
}pending appears only when true; notes appears only when nonempty. Set verbose=True on get_transactions or search_transactions for full transaction details, or on get_transaction_categories for full category details.
Sessions are cached in ~/.monarch-mcp/ for faster subsequent logins (override the location with the MONARCH_SESSION_DIR env var). If you hit auth issues:
Delete ~/.monarch-mcp/session.pickle to clear the cached session
Set MONARCH_FORCE_LOGIN=true in your env config to force a fresh login
Make sure your system clock is accurate (required for TOTP)
For live checks, create a .env file (git-ignored) and load it explicitly with uv --env-file:
MONARCH_EMAIL="your-email@example.com"
MONARCH_PASSWORD="your-password"
MONARCH_MFA_SECRET="YOUR_TOTP_SECRET_KEY"uv run pytest tests/ -v # offline; live tests are skipped
MONARCH_RUN_INTEGRATION=true uv run --env-file .env pytest tests/test_integration.py -v
uv run --env-file .env scripts/health_check.py # live API connectivity checkIntegration tests share one fresh login to avoid MFA reuse and login throttling. They never load .env themselves or read/write saved sessions.
Run the same checks as CI:
uv run python scripts/ci.pyUse /release to bump pyproject.toml, commit, tag vX.Y.Z, push, and create a GitHub release. The publish workflow publishes to PyPI and the MCP Registry through OIDC, setting server.json versions from the tag.
Measure tool calls and output sizes:
uv run scripts/analyze_logs.py # full report
uv run scripts/analyze_logs.py --json # JSON output
uv run scripts/eval_session.py snapshot # mark log position
# ... use tools in Claude ...
uv run scripts/eval_session.py analyze # analyze new entriesWarning: This server uses unofficial Monarch Money API access. Your credentials grant full account access, including writes.
The server runs locally and returns requested financial data to your MCP client. Review the client's privacy settings and tool approvals.
Protect your password and MFA secret. The TOTP secret enables ongoing code generation.
Session files in ~/.monarch-mcp/ contain auth tokens. Protect them and any custom MONARCH_SESSION_DIR.
Logs can include financial input values and error details. Review them before sharing.
Never commit credential-bearing .env, .mcp.json, or client config files.
Monarch Money may change or restrict unofficial API access at any time.
Forked from colvint/monarch-money-mcp. API access uses bradleyseanf/monarchmoneycommunity, based on hammem/monarchmoney. Source installs pin a commit; PyPI installs use the published library.
Intelligent spending pattern analysis with trend forecasting.
Combines multiple data sources to provide deep spending insights including:
Monthly spending trends by category
Account usage patterns
Budget performance analysis
Predictive spending forecasts
Args: lookback_months: Number of months to analyze (default 6) include_forecasting: Whether to include spending forecasts
| Name | Required | Description | Default |
|---|---|---|---|
| lookback_months | No | ||
| include_forecasting | No |
| Name | Required | Description |
|---|---|---|
| forecast | No | |
| metadata | No | |
| account_usage | No | |
| monthly_trends | No | |
| analysis_period | No | |
| category_analysis | No | |
| budget_performance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows it is safe. The description adds value by detailing that the tool 'combines multiple data sources' and produces forecasts, budget analysis, and account usage patterns, which are not implied by the annotation alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and uses bullet points for clarity. However, the 'Args' section is redundant with the schema and could be removed to reduce length. Every sentence serves a purpose, but the structure is not maximally 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?
Given that an output schema exists, the description does not need to detail return values. It covers the key analytical aspects (trends, forecasts, budget performance, account usage). No critical gaps are apparent for a read-only analytical tool, though it could mention any limits on data scope.
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%, so the description must compensate. It restates the parameter names and defaults (already in schema) but adds little additional meaning. For example, it says include_forecasting is 'whether to include spending forecasts', adding no nuance beyond the parameter name. The description does not explain valid ranges, formats, or effects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'intelligent spending pattern analysis with trend forecasting' and lists specific insights (monthly trends, account usage, budget performance, forecasts). This distinguishes it from simpler siblings like get_spending_summary, though it could be more explicit about its comparative advantage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_spending_summary or get_cashflow. It lacks explicit when-to-use, when-not-to-use, or alternative recommendations, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a manually tracked account.
| Name | Required | Description | Default |
|---|---|---|---|
| balance | Yes | ||
| account_name | Yes | ||
| account_type | Yes |
| Name | Required | Description |
|---|---|---|
| account | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (not read-only, not destructive), but adds no additional behavioral details such as duplication handling or side effects. Annotations already indicate basic safety profile, but description does not enrich beyond that.
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 extremely short and front-loaded, making it quickly readable. However, it sacrifices essential details for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 3 required parameters and a presumably existing output schema, the description provides no context about side effects, constraints, or return values. It is insufficient for an agent to use correctly without extra inference.
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 0% schema description coverage, the description fails to add any meaning to the three required parameters. No parameter details or examples are provided, leaving the agent with only field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('manually tracked account'), making the purpose immediately understandable. It distinguishes from sibling tools as it is the only creation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or context. It simply states the action without explaining scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new manual transaction.
Args: amount: Transaction amount (positive for income, negative for expense) merchant_name: Name of the merchant/payee (e.g., "Starbucks", "Monthly Rent") account_id: ID of the account for this transaction date: Transaction date in YYYY-MM-DD format category_id: ID of the category to assign (required for new transactions) notes: Optional notes/memo for this transaction update_balance: Whether to update account balance when creating this transaction (default: False) - False: Transaction is recorded but doesn't affect account balance (typical for synced accounts) - True: Adjusts account balance by transaction amount (useful for manual accounts)
Returns: JSON string with created transaction details
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| notes | No | ||
| amount | Yes | ||
| account_id | Yes | ||
| category_id | Yes | ||
| merchant_name | Yes | ||
| update_balance | No |
| Name | Required | Description |
|---|---|---|
| transaction | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, so the agent knows this is a write operation. The description adds value by explaining the update_balance parameter's effects, confirming it mutates account balance when true. It also mentions the return format (JSON string). However, it does not explicitly state that the operation is not idempotent, which matches the idempotentHint=false annotation.
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 well-structured with a clear opening line and bullet-style parameter explanations. Every sentence adds value, though the update_balance explanation could be slightly condensed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters and an output schema (declared), the description covers the creation action, all parameter meanings, return type, and a key behavioral option (update_balance). Missing aspects include validation or error scenarios (e.g., invalid account_id), but the description is still fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter's meaning, format, and constraints. For example, amount is described as 'positive for income, negative for expense', date as 'YYYY-MM-DD', and update_balance with use cases.
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 explicitly states 'Create a new manual transaction,' which is a specific verb-resource combination. This clearly distinguishes it from sibling tools like update_transaction or get_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides contextual guidance on when to set update_balance to True vs False based on account type (synced vs manual). However, it does not explicitly tell the agent when to use this tool over other transaction-related tools, such as syncing or importing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get historical account balance data.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | ||
| account_id | Yes | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| history | Yes | |
| account_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'historical' context beyond annotations, but fails to disclose other behaviors such as pagination, time range constraints, or rate limits. Annotations already declare readOnlyHint true, so safety is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure. No front-loading of key details beyond the basic purpose.
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 three parameters and an output schema, the description is insufficient. It does not explain return values or parameter behavior, leaving significant gaps for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and the tool description does not explain any parameter semantics (e.g., date formats, meaning of account_id). All three parameters are left 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?
The description clearly states the tool retrieves historical account balance data, using a specific verb and resource. It distinguishes from sibling tools like get_accounts (current balances) by specifying 'historical'.
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 is provided on when to use this tool versus alternatives like get_accounts or get_transactions. The description does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get investment portfolio data (holdings) for a brokerage account.
Args: account_id: ID of the investment/brokerage account to fetch holdings for.
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes |
| Name | Required | Description |
|---|---|---|
| holdings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds that the tool returns portfolio holdings, which is consistent but does not disclose additional behavioral traits such as data freshness, pagination, or required permissions. The low burden from annotations keeps this at a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two short sentences plus an 'Args' block. It front-loads the key purpose and immediately clarifies the parameter. Every sentence earns its place with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, read-only operation, output schema present), the description is nearly complete. It explains the parameter meaning and purpose. The presence of an output schema means return details are handled elsewhere, so the description does not need to elaborate. Minor improvement could mention that holdings are for investments, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 0% description coverage, placing the full burden on the description. The description explains that 'account_id' is the ID of the investment/brokerage account, which adds meaning beyond the raw schema. For a single parameter, this is sufficient, though more detail on format or validation would improve 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?
The description clearly states the tool retrieves investment portfolio data (holdings) for a brokerage account, using a specific verb ('get') and resource ('holdings'). It distinguishes itself from siblings like 'get_account_history' or 'get_accounts' by specifying 'holdings' and 'brokerage account', leaving no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention what cases it is suitable for, nor does it exclude any scenarios. Given the many sibling tools (e.g., get_account_history, get_accounts), the agent needs explicit direction to select correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all linked financial accounts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| accounts | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's 'Retrieve' aligns. No additional behavioral details (e.g., what 'linked' means) are added beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence of 5 words, front-loading the action and resource with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, clear annotations, and an existing output schema, the description is adequate for a straightforward list tool, though it could mention response scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'all linked financial accounts', distinguishing it from siblings like get_account_history or get_account_holdings.
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 usage guidance is provided. The description does not specify when to use this tool versus alternatives, nor does it mention any context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve budget information with flexible date filtering.
Args: start_date: Filter budgets from this date onwards. Supports natural language like 'last month', 'this year' end_date: Filter budgets up to this date. Supports natural language
Returns: JSON string containing budget information
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| budgets | Yes | |
| message | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true. Description adds that it returns a JSON string and supports natural language dates, which is useful context. However, it doesn't disclose pagination, limits, or default behavior beyond basic retrieval.
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?
Relatively concise but includes an 'Args' section that partially duplicates schema information. The natural language hint is valuable. Could be more front-loaded without the structured list.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the tool is simple (2 optional params), the description is adequate but lacks defaults, ordering, and scope (e.g., returns all budgets or only filtered?). Missing context on what happens with no dates.
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 has 0% description coverage, so the description carries the full burden. It explains both parameters (start_date, end_date) with purpose and natural language support, significantly adding meaning beyond the schema's minimal type info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve budget information with flexible date filtering', specifying the action (retrieve), resource (budgets), and distinctive feature (date filtering). It stands out from siblings like 'set_budget_amount' (write) and 'analyze_spending_patterns' (analysis).
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 explicit guidance on when to use this vs. other budget-related tools like 'set_budget_amount' or 'analyze_spending_patterns'. No when-not-to-use or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze cashflow data with flexible date filtering.
Args: start_date: Filter cashflow from this date onwards. Supports natural language like 'last month', 'this year' end_date: Filter cashflow up to this date. Supports natural language
Returns: JSON string containing cashflow analysis
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| cashflow | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds no additional behavioral context beyond the date filtering flexibility. It does not contradict annotations and adds minimal extra information.
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 concise, front-loaded with the main purpose, and uses a clear Args structure. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional params), the presence of annotations (readOnlyHint) and an output schema, the description adequately covers the return format (JSON string) and usage context. No significant gaps.
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%, but the description provides meaningful semantics for both parameters including natural language support examples (e.g., 'last month', 'this year'). This compensates for the lack of 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?
The description clearly states 'Analyze cashflow data with flexible date filtering', which uses a specific verb and resource. This distinguishes it from sibling tools like get_transactions or analyze_spending_patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for cashflow analysis with date filtering but does not explicitly state when to use vs alternatives or when not to use. It provides clear context but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get complete financial overview in a single call - accounts, transactions, budgets, cashflow.
This intelligent batch tool combines multiple API calls to provide comprehensive financial analysis, reducing round-trips and providing deeper insights.
Args: period: Time period for analysis ("this month", "last month", "this year", etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | this month |
| Name | Required | Description |
|---|---|---|
| period | Yes | |
| budgets | No | |
| accounts | No | |
| cashflow | No | |
| categories | No | |
| transactions | No | |
| batch_metadata | No | |
| transaction_summary | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=false, so safety is clear. The description adds that it combines multiple API calls and reduces round-trips, but the term 'deeper insights' is vague. No additional behavioral traits beyond annotations are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the core purpose in the first sentence. The second sentence adds moderate value but contains marketing language ('intelligent batch tool', 'deeper insights') that could be trimmed.
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 an output schema exists, the description does not need to detail return values. It sufficiently explains the tool's scope and the single parameter. However, it lacks mention of any prerequisites or limitations.
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 0% schema description coverage, the description bears full responsibility for explaining the single parameter. It provides examples of valid period values ('this month', 'last month', etc.), adding meaning beyond the schema's basic definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to get a complete financial overview including accounts, transactions, budgets, and cashflow. It distinguishes itself from sibling tools by highlighting its batching capability, using specific verbs and resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining comprehensive data in one call, but lacks explicit guidance on when not to use it or alternatives. Given many sibling tools exist for individual data, it would benefit from specifying trade-offs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get linked financial institutions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| institutions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint: true, so the description adds no additional behavioral context. However, the description is consistent and does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with no extraneous information. Every word 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 parameterless list tool with an output schema, the description is complete enough. It tells the agent exactly what the tool returns.
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 no parameters, so the description does not need to detail them. The schema coverage is 100%, meeting the baseline without additional description.
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 'Get linked financial institutions' uses a specific verb ('Get') and resource ('linked financial institutions'), clearly distinguishing it from sibling tools that focus on accounts, transactions, or budgets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. While the purpose is clear, the description lacks context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get scheduled recurring transactions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| recurring | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds no extra value. It is not contradictory.
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?
Extremely concise at 4 words, front-loaded, and no wasted 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 an output schema and no parameters, the description is adequate; could hint at usage context but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; baseline of 4 for zero-parameter tools 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?
Clearly states it retrieves scheduled recurring transactions, distinguishing it from sibling tools like get_transactions which likely retrieves all transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_transactions or get_spending_summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get intelligent spending summary with aggregations.
Args: start_date: Start date (supports natural language like 'last month') end_date: End date (supports natural language) group_by: Group spending by 'category', 'account', or 'month'
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | ||
| group_by | No | category | |
| start_date | No |
| Name | Required | Description |
|---|---|---|
| groups | Yes | |
| period | Yes | |
| totals | Yes | |
| group_by | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description adds some value by mentioning natural language date support and aggregation grouping. However, it does not elaborate on aggregation details, performance, or data scope, which would further enhance transparency.
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 concise, with two sentences and a bullet list for parameters. Every element adds value, though the bullet list could be integrated more tightly into the main 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 an output schema present (though not shown), the description need not detail return values. However, it does not specify what aggregations are computed (e.g., total spending, averages) or include any caveats, leaving some gaps for a tool with three parameters and no required inputs.
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%, so the description compensates by explaining that start_date and end_date support natural language and that group_by accepts 'category', 'account', or 'month'. This adds significant meaning beyond the bare schema types, though it could mention defaults and optionality.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets an intelligent spending summary with aggregations, specifying the verb and resource. However, it does not distinguish this tool from siblings like analyze_spending_patterns or get_cashflow, which may also provide spending summaries.
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. The description only explains what the tool does, not when it should be chosen over siblings like get_complete_financial_overview or analyze_spending_patterns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all transaction categories.
Args: verbose: Output format control (default: False) - False: Returns compact format with just {id, name} per category (~80% smaller). Ideal for category lookups when mapping names to IDs. - True: Returns full category details including group, order, timestamps, system flags.
Returns: JSON string containing category list
| Name | Required | Description | Default |
|---|---|---|---|
| verbose | No |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| verbose | Yes | |
| categories | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, confirming a safe read operation. The description adds behavioral context by detailing the two output formats (compact vs. full) and their use cases, going beyond the annotation's minimal information.
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 concise with a clear Args/Returns structure. Every sentence adds value, no fluff. It is appropriately front-loaded with the core purpose, and the parameter details are well-organized.
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 an output schema, the description covers the essential behavior and parameter semantics. It does not mention if categories are filterable or how they relate to transactions, but these are not critical given the tool's narrow scope.
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%, but the description fully compensates by exhaustively explaining the single 'verbose' parameter: its default, both output modes, their structure, and when to use each. This adds significant 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 'List all transaction categories.' This is a clear verb+resource combination. It distinguishes itself from sibling tools (e.g., get_transactions, get_budgets) by focusing specifically on categories, which no other tool covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance for the verbose parameter, explaining when to use each mode (e.g., compact mode for lookups, full mode for details). However, it does not include explicit when-to-use or when-not-to-use context relative to alternatives, though the tool's uniqueness makes this less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch transactions with flexible date filtering and smart output formatting.
Args: limit: Maximum number of transactions to return (default: 100, max: 1000) offset: Number of transactions to skip for pagination (default: 0) start_date: Filter transactions from this date onwards. Supports natural language like 'last month', 'yesterday', '30 days ago' NOTE: If you provide start_date without end_date, end_date will auto-default to 'today' end_date: Filter transactions up to this date. Supports natural language NOTE: If you provide end_date without start_date, start_date will auto-default to 'this month' account_id: Filter by specific account ID (converted to list internally) category_id: Filter by specific category ID (converted to list internally) tag_ids: Comma-separated tag IDs to filter by (e.g., "tag1,tag2") has_attachments: Filter to transactions with (True) or without (False) attachments has_notes: Filter to transactions with (True) or without (False) notes hidden_from_reports: Include hidden transactions (True), exclude them (False), or show all (None) is_split: Filter to split transactions only (True) or non-split (False) is_recurring: Filter to recurring transactions only (True) or non-recurring (False) verbose: Output format control (default: False) - False (compact mode): Returns essential fields only (~80% smaller) Fields included: id, date, amount, merchant, plaidName, category, account, pending, needsReview, notes
- True (verbose mode): Returns ALL fields including:
Essential fields (same as compact) PLUS:
• hideFromReports (bool)
• reviewStatus (str: "needs_review" | "reviewed" | null)
• isSplitTransaction (bool)
• isRecurring (bool)
• attachments (list of attachment objects)
• tags (list of tag objects)
• createdAt (ISO timestamp)
• updatedAt (ISO timestamp)
• __typename (GraphQL metadata)
• Full nested objects with all their fields
Use verbose=False for most queries to reduce token usage.
Use verbose=True when you need: timestamps, split info, attachment details,
or are updating transactions (need full context).Key Transaction Fields: Core Identifiers: - id: Unique transaction ID (required for updates) - date: Transaction date (YYYY-MM-DD format) - amount: Transaction amount (negative = expense, positive = income)
Merchant Information:
IMPORTANT: Monarch normalizes merchant names for cleaner UI
- merchant.name: User-facing display name shown in Monarch UI (normalized/cleaned)
Example: "Chipotle" for all Chipotle locations
- plaidName: Original bank statement text from Plaid/institution (raw data)
Example: "CHIPOTLE 4963", "CHIPOTLE MEX GR ONLINE", "CHIPOTLE 1879"
Use this to see location numbers or original descriptors
- Multiple transactions from different locations share the same merchant.name
- Use plaidName to distinguish between specific locations/variants
Categorization:
- category.id: Category ID (for filtering/updates)
- category.name: Category display name (e.g., "Restaurants & Bars")
- tags: List of tag objects applied to transaction
Account Info:
- account.id: Account ID where transaction occurred
- account.displayName: Account name (e.g., "Main Credit Card")
Status Flags:
- pending: True if transaction hasn't cleared yet
- needsReview: True if flagged for user review
- reviewStatus: "needs_review", "reviewed", or null
- hideFromReports: True if hidden from budget/reports
Transaction Types:
- isSplitTransaction: True if split into multiple categories
- isRecurring: True if part of a recurring series
User Annotations:
NOTE: These are different fields with different purposes
- notes: Free-form user memo/annotation (e.g., "Business lunch with client")
- merchant_name: The merchant's display name (e.g., "Olive Garden")
- Both are editable, but serve different purposes in the UI
- attachments: List of receipt/document attachments
Metadata (verbose mode only):
- createdAt: When transaction was first imported
- updatedAt: Last modification timestamp
- __typename: GraphQL type informationReturns: JSON string containing transaction list
Common Filter Examples: - Unreviewed transactions: has_notes=False, needs_review=True - Split transactions: is_split=True - Transactions with receipts: has_attachments=True - Manual transactions: synced_from_institution=False
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| tag_ids | No | ||
| verbose | No | ||
| end_date | No | ||
| is_split | No | ||
| has_notes | No | ||
| account_id | No | ||
| start_date | No | ||
| category_id | No | ||
| is_recurring | No | ||
| has_attachments | No | ||
| hidden_from_reports | No |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| verbose | Yes | |
| transactions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description details pagination, date auto-defaults, natural language date support, verbose vs compact output modes, and internal parameter handling (e.g., converting account_id to list). This fully discloses behavioral traits.
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 well-structured with headings but is very long, containing a large reference section on transaction fields that could be streamlined. While detailed, it sacrifices conciseness, especially for a tool with 13 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity and the absence of an output schema (only indicated as present), the description covers parameters, output fields, and examples thoroughly. It omits error handling and edge cases (e.g., exceeding limit max), but overall provides a comprehensive picture.
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 0% schema description coverage, the description compensates extensively by explaining each parameter's purpose, default values, data types, and special behaviors (e.g., 'converted to list internally', 'auto-default to today'). It even includes common filter examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch transactions with flexible date filtering and smart output formatting,' specifying the verb and resource. It distinguishes from siblings by focusing on filtering and output formatting, but does not explicitly differentiate from 'search_transactions' or other related 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?
The description provides filtering examples but no explicit guidance on when to use this tool versus alternatives like 'search_transactions' or 'get_complete_financial_overview'. It lacks when-not-to-use scenarios or tool selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the split legs of a transaction.
Splitting lets a single transaction be divided across multiple categories (e.g. a Target run that is part groceries, part household). This returns the current split legs, if any.
Args: transaction_id: ID of the transaction to inspect
Returns:
The transaction id, whether it currently has splits, and the list of
split legs (each with its own amount, category, merchant, and notes).
splits is empty for an un-split transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes |
| Name | Required | Description |
|---|---|---|
| splits | Yes | |
| transaction_id | Yes | |
| has_split_transactions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=false. The description adds behavioral context: it returns the current split legs, and for un-split transactions, 'splits' is empty. This goes beyond the annotations by clarifying the return shape in edge cases.
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 well-structured with a clear statement of purpose, an example, and separate Args/Returns sections. It is slightly verbose but every sentence adds value. Could be trimmed slightly, but overall effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, read-only, output schema exists), the description is complete. It explains the concept, the single parameter, and the return structure including the empty case. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the parameter, but the description explicitly documents 'transaction_id: ID of the transaction to inspect'. This compensates for the schema gap by adding meaning to the single required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get the split legs of a transaction.' It explains what splitting is with a concrete example ('Target run that is part groceries, part household'), making the intent unmistakable. It also contrasts with sibling tools like 'update_transaction_splits' by focusing on retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly state when to use it versus alternatives. It implies usage when you need to inspect existing splits, but there is no mention of when not to use it or which sibling tools (e.g., update_transaction_splits) are appropriate for modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request a refresh of all account data from financial institutions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose that this is likely a network-triggering, potentially slow, and rate-limited operation. Annotations are all false, so no safety hints are conveyed beyond the description, which lacks behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's purpose without extraneous words. It is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and an output schema, the description is minimally adequate. However, it lacks context about side effects, expected duration, or when results are available, which is needed given the imperative nature of 'refresh'.
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 0 parameters and 100% schema coverage, the schema fully documents the absence of parameters. The description adds no parameter information, meeting the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'refresh' and the resource 'account data from financial institutions', indicating it triggers a data sync. It distinguishes from sibling tools like 'get_accounts' which likely retrieve cached data without initiating a refresh.
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 is provided on when to use this tool versus alternatives like 'get_accounts' or 'create_manual_account'. The description does not mention prerequisites, timing, or whether it should be called sparingly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search transactions by text using Monarch Money's built-in search.
Searches merchant names, descriptions, notes, and other fields. Accepts all the same filters as get_transactions plus a search query. Returns compact results by default (use verbose=True for full details).
Args: query: Search term to find in transactions limit: Maximum transactions to return (default: 500, max: 1000) offset: Number of transactions to skip for pagination start_date: Filter from this date (supports natural language like 'last month') end_date: Filter to this date (supports natural language) account_id: Filter by specific account ID category_id: Filter by specific category ID tag_ids: Comma-separated tag IDs to filter by has_attachments: Filter by attachment presence has_notes: Filter by notes presence hidden_from_reports: Filter by report visibility is_split: Filter split transactions is_recurring: Filter recurring transactions verbose: False=compact fields, True=all fields
Returns: JSON with search_metadata and matching transactions
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| offset | No | ||
| tag_ids | No | ||
| verbose | No | ||
| end_date | No | ||
| is_split | No | ||
| has_notes | No | ||
| account_id | No | ||
| start_date | No | ||
| category_id | No | ||
| is_recurring | No | ||
| has_attachments | No | ||
| hidden_from_reports | No |
| Name | Required | Description |
|---|---|---|
| transactions | Yes | |
| search_metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, consistent with the search operation. The description adds behavioral details: 'Returns compact results by default (use verbose=True for full details).' No contradiction.
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 well-structured with a clear opening sentence, followed by details and an Args section. While moderately long, every part adds value; could be slightly more concise but effective.
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 14 parameters, zero schema description coverage, and an output schema, the description covers all parameter semantics, return format ('JSON with search_metadata and matching transactions'), and default behaviors. Completeness is high.
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 description coverage at 0%, the description provides extensive parameter explanations: lists all 14 parameters, explains 'query' as search term, describes 'verbose' behavior, and notes natural language support for dates ('last month'). This adds significant value beyond bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search transactions by text using Monarch Money's built-in search.' It lists fields searched (merchant names, descriptions, notes) and distinguishes itself from get_transactions by noting it accepts the same filters plus a search query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating it accepts all get_transactions filters plus a search query, suggesting use when text search is needed. However, it does not explicitly state when not to use or name alternatives beyond get_transactions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set budget amount for a category.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | ||
| category_id | Yes |
| Name | Required | Description |
|---|---|---|
| amount | Yes | |
| result | Yes | |
| category_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false, so the description's claim of setting an amount is consistent. However, the description adds no further behavioral context (e.g., whether it overwrites or adjusts existing budgets, permission requirements, or side effects), relying entirely on annotations for transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core action efficiently. However, it is overly brief and could afford to include parameter hints without losing conciseness.
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 two-parameter tool with an output schema, the description is adequate but lacks parameter semantics and usage context. It does not explain how the amount is interpreted (e.g., currency, decimal places), which is necessary for correct use.
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 description does not explain the parameters beyond their names. The agent receives no guidance on valid values, formatting, or meaning of 'category_id' and 'amount'. This is a significant gap for correct invocation.
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 'Set budget amount for a category.' uses a specific verb ('set') and clearly identifies the resource ('budget amount') and scope ('for a category'), effectively differentiating from sibling tools like 'get_budgets' and 'analyze_spending_patterns' which are read or analysis operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for setting budget amounts, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. The context from sibling tools provides some differentiation, but the description itself offers no usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing transaction.
Args: transaction_id: ID of the transaction to update (required) amount: New transaction amount merchant_name: New merchant display name shown in Monarch UI - This updates the user-facing name (merchant.name field) - Does NOT change plaidName (original bank statement text, read-only) - Empty strings are ignored by the API - Example: Change "AMZN Mktp US" to "Amazon" category_id: ID of the new category to assign date: New transaction date in YYYY-MM-DD format notes: User notes/memo for this transaction (separate from merchant name) NOTE: This is different from merchant_name - notes: Free-form user memo/annotation (e.g., "Business lunch with client") - merchant_name: The merchant's display name (e.g., "Olive Garden") - Both are editable, but serve different purposes in the UI - Use empty string "" to clear existing notes goal_id: ID of savings goal to associate with this transaction - Use empty string "" to clear goal association hide_from_reports: Whether to hide this transaction from reports/analytics needs_review: Flag transaction as needing review
Field Editability: Editable Fields (can be updated): - amount: Transaction amount - merchant_name: User-facing merchant display name - category_id: Category assignment - date: Transaction date - notes: User memo/notes - goal_id: Goal association - hide_from_reports: Visibility in reports - needs_review: Review flag
Read-Only Fields (cannot be updated):
- id: Transaction ID (immutable)
- plaidName: Original bank statement text (from institution)
- account: Account where transaction occurred
- pending: Pending status (controlled by institution)
- createdAt: Creation timestamp
- isSplitTransaction: Split status (use separate split API)
- attachments: Use separate attachment APIReturns: JSON string with updated transaction details
Common Use Cases: - Change merchant: merchant_name="Starbucks" - Add note: notes="Business expense" - Recategorize: category_id="cat_groceries_123" - Mark for review: needs_review=True - Clear notes: notes=""
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| notes | No | ||
| amount | No | ||
| goal_id | No | ||
| category_id | No | ||
| needs_review | No | ||
| merchant_name | No | ||
| transaction_id | Yes | ||
| hide_from_reports | No |
| Name | Required | Description |
|---|---|---|
| transaction | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: clarifies that empty strings are ignored for merchant_name, notes can be cleared with empty string, and lists read-only fields (plaidName, account, etc.). It details side effects and constraints, which is critical since annotations only provide high-level hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (Args, Field Editability, Returns, Common Use Cases) and bullet points. Every sentence adds value, and the key information is front-loaded. Despite length, it remains organized and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no schema descriptions, output schema present), the description covers all necessary aspects: parameter behaviors, edge cases, read-only fields, and example use cases. It is complete and leaves no ambiguity for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing detailed explanations for each parameter, including examples, field differences (notes vs. merchant_name), and behavioral notes (e.g., empty string behavior). This adds substantial meaning beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing transaction' and lists all updatable fields. However, it does not explicitly differentiate from sibling tools like 'update_transactions_bulk' or 'create_transaction', which could cause ambiguity for an agent deciding which tool to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides common use cases and field editability details, but does not give explicit guidance on when to use this tool versus alternatives (e.g., create_transaction for new transactions, update_transactions_bulk for batch updates). The usage context is implied but not contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update multiple transactions in a single call to save round-trips.
This is much more efficient than calling update_transaction multiple times. Updates are executed in parallel for maximum performance.
Args: updates: JSON string containing list of transaction updates. Each update should have: - transaction_id (required): ID of transaction to update - amount (optional): New amount - merchant_name (optional): New merchant display name - category_id (optional): New category ID - date (optional): New date in YYYY-MM-DD format - notes (optional): New notes - goal_id (optional): Goal ID or empty string to clear - hide_from_reports (optional): Boolean visibility flag - needs_review (optional): Boolean review flag
Example: [ {"transaction_id": "123", "category_id": "cat_456", "notes": "Updated"}, {"transaction_id": "789", "merchant_name": "Starbucks", "needs_review": false} ]
Returns: JSON with results for each transaction including successes and any failures
| Name | Required | Description | Default |
|---|---|---|---|
| updates | Yes |
| Name | Required | Description |
|---|---|---|
| message | No | |
| results | Yes | |
| summary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint=true, etc.), it discloses parallel execution and return format (JSON with results per transaction). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, front-loaded purpose, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description succinctly covers the return value. All relevant aspects are addressed.
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 has 0% description coverage, but the description fully explains the JSON structure, required/optional fields, types, format, and provides an example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update multiple transactions in a single call' and contrasts with the sibling tool update_transaction, distinguishing it effectively.
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 notes efficiency over calling update_transaction multiple times, implying when to use it. Lacks explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create, replace, or remove the splits on a transaction.
This is a full replacement: the splits you pass become the transaction's complete set of split legs, replacing any that exist. Pass an empty list to remove all splits and restore the transaction to a single un-split entry.
Args: transaction_id: ID of the transaction to split (required) splits: The complete set of split legs. Each leg has: - amount (required): Leg amount, using the parent's sign convention (expenses negative, income positive). All leg amounts MUST sum to the parent transaction's amount or Monarch rejects the update. - category_id (optional): Category for this leg - merchant_name (optional): Merchant display name for this leg; defaults to the parent merchant when omitted - notes (optional): Per-leg memo Pass an empty list to delete all existing splits.
Example: Split a -100.00 transaction into groceries and household: transaction_id="txn_123" splits=[ {"amount": -70.00, "category_id": "cat_groceries", "notes": "Food"}, {"amount": -30.00, "category_id": "cat_household"}, ]
Returns: The transaction id, whether it now has splits, the resulting split legs, and a human-readable summary message.
| Name | Required | Description | Default |
|---|---|---|---|
| splits | Yes | ||
| transaction_id | Yes |
| Name | Required | Description |
|---|---|---|
| splits | Yes | |
| message | Yes | |
| transaction_id | Yes | |
| has_split_transactions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare idempotentHint=true and destructiveHint=false, and the description adds rich behavioral context: full replacement behavior, amount summing constraint, sign convention, default merchant, and return structure. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, bullet-style argument list, example, and return info. It is appropriately sized for the complexity; each sentence adds value. Slightly verbose 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?
Given two parameters, no nested objects, and an output schema, the description covers purpose, behavior, parameter details, constraints, example, and return values. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully documents both parameters: transaction_id (required) and splits (complete set with amount required, sign convention, optional fields). An example clarifies usage. This compensates fully for the lack of 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?
The description clearly states the tool creates, replaces, or removes splits on a transaction. It specifies the verb (create/replace/remove) and resource (splits). However, it does not explicitly differentiate from sibling tools like update_transaction or get_transaction_splits, though the purpose 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?
The description explains when to use the tool (to replace splits or remove them with an empty list) and provides detailed argument semantics. It lacks explicit when-not-to-use guidance or alternatives (e.g., use get_transaction_splits to read), but the sibling list gives context.
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.
v0.4.0get_transaction_splitsupdate_transaction_splitsv0.3.2analyze_spending_patternscreate_manual_accountcreate_transactionget_account_historyget_account_holdingsget_accountsget_budgetsget_cashflowget_complete_financial_overviewget_institutionsget_recurring_transactionsget_spending_summaryget_transaction_categoriesget_transactionsrefresh_accountssearch_transactionsset_budget_amountupdate_transactionupdate_transactions_bulkScored across 21 tools
Most tools have clearly distinct purposes, but there is some overlap among spending analysis tools (analyze_spending_patterns, get_spending_summary, get_cashflow, get_complete_financial_overview). While descriptions differentiate them, an agent might still struggle to choose the right one without careful reading.
All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., analyze_spending_patterns, create_transaction, get_accounts, update_transaction_splits). No mixed conventions or unexpected styles.
21 tools is slightly above the typical range, but each serves a distinct purpose in the personal finance domain. The count feels justified given the breadth of features (accounts, transactions, budgets, categories, analysis).
The tool surface covers most core personal finance operations: account management, transactions with CRUD and splits, budgets, categories, and various analyses. Missing are deletion endpoints (e.g., delete account/transaction) and investment transaction details, but these are not essential for common workflows.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
An MCP server that integrates with Discord to provide AI-powered features.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
