The Monarch Money MCP Server gives AI assistants read/write access to your Monarch Money financial data. Key capabilities include:
Account Management
List accounts with balances, view balance history, get investment holdings, create manual accounts, refresh linked account data, and view linked institutions.
Transaction Management
Fetch, search (by merchant/keyword), create, update, and bulk-update transactions. Supports flexible filtering by date, account, category, tags, notes, split/recurring flags, and review status.
Budgeting & Cashflow
View budgets, set budget amounts for categories, and analyze income vs. expense cashflow over a time period.
Spending Analysis
Get aggregated spending summaries grouped by category, account, or month (get_spending_summary), multi-month trend analysis with forecasting (analyze_spending_patterns), and a single-call batch tool (get_complete_financial_overview) that fetches accounts, transactions, budgets, cashflow, and categories in parallel.
Categories & Recurring Transactions
List transaction categories (compact or verbose) and view recurring transactions detected by Monarch Money.
Key Features
Natural language date parsing (e.g., "last month", "30 days ago")
Token-efficient compact output (~80% smaller payloads by default)
MCP resources for quick access to categories, accounts, institutions, and per-account data
MCP prompts for guided financial analysis workflows
Designed for local execution so credentials never pass through the LLM
Click on "Install 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.
An MCP server for Monarch Money — gives AI assistants like Claude access to your financial accounts, transactions, budgets, and more.
Originally forked from @colvint/monarch-money-mcp but has diverged into a full rewrite on a modern FastMCP architecture. It's grown from a handful of tools to a broad toolset — adding server-side transaction search, parallel bulk transaction updates, multi-month spending-pattern analysis with forecasting, and a single-call financial overview that fans out to five Monarch APIs at once. Responses are tuned hard for token efficiency: the default compact transaction format cuts payload size by ~80%, categories return just id+name unless you ask for more, and every tool accepts a verbose flag when you want the full payload. It also ships MCP resources and guided prompts, natural-language date parsing ("last month", "30 days ago"), and proper read/write tool annotations so clients know what's safe to call.
Built on the monarchmoneycommunity library by @bradleyseanf — an actively-maintained community fork that tracks the latest Monarch Money API changes (the api.monarch.com domain move, gql 4.0, auth persistence) with full MFA support, pinned to a specific commit for reproducible builds. It descends from the original monarchmoney library by @hammem, which is no longer actively maintained.
Tools covering accounts, transactions, budgets, cashflow, investments, categories, recurring transactions, and spending analysis
Structured output — every tool returns a typed schema (outputSchema + machine-readable structured content) with a text fallback for older clients
MCP resources for quick access to categories, accounts, and institutions, plus parameterized templates for per-account holdings and history (accounts://{account_id}/holdings|history)
MCP prompts for guided financial analysis workflows, with live argument autocompletion
Smart output formatting — compact transaction format reduces token usage by ~80%
Natural language dates — "last month", "30 days ago", "this year" all work
Batch operations — parallel multi-account queries, bulk transaction updates, with progress reporting
Spending analysis — multi-month trend analysis with category/account breakdowns
Tool annotations & titles — read/write metadata and human-friendly titles for MCP clients
Related MCP server: Lunch Money MCP Server
One-line install, no clone, no absolute-path wrangling. The server is published to PyPI, so uv runs it on demand with uvx monarch-mcp-jamiew. You'll need uv installed and your Monarch credentials (see Getting your MFA secret below).
Every MCP client uses the same shape — command uvx, package monarch-mcp-jamiew, and your three credentials as env vars:
{
"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"
}
}
}
}Pick your client below for the exact steps.
Edit your config file (create it if it doesn't exist) and add the standard config above under mcpServers:
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" }Drop the standard config into a .mcp.json file at your project root. Claude Code (project scope) and most clients auto-load it.
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.
Most accept the same standard config — drop it into the client's MCP config (e.g. Cursor's ~/.cursor/mcp.json, or VS Code via code --add-mcp). Anything that speaks MCP over stdio works.
Not sure how? Tell your agent:
Install the Monarch Money MCP server from https://github.com/jamiew/monarch-mcp — it's on PyPI as
monarch-mcp-jamiew, runs viauvx monarch-mcp-jamiew, and needs env varsMONARCH_EMAIL,MONARCH_PASSWORD, andMONARCH_MFA_SECRET.
To run against a local checkout (and the git-pinned monarchmoneycommunity lib):
git clone https://github.com/jamiew/monarch-mcp
cd monarch-mcp
uv syncThen 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 / codex mcp add one-liners put your credentials in shell history. If that bothers you, edit the client's config file directly (as shown for Claude Desktop / Codex above) instead.
Go to Monarch Money settings and enable 2FA
When shown the QR code, look for "Can't scan?" or "Enter manually"
Copy the secret key (a string like T5SPVJIBRNPNNINFSH5W7RFVF2XYADYX)
Use this as your MONARCH_MFA_SECRET
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 |
| Budget data and spending analysis |
| Income and expense analysis |
| Investment holdings for an account (requires |
| Account balance history |
| Linked financial institutions |
| Recurring transaction detection |
| Set a budget category amount |
| Create a manually-tracked account |
| Trigger account data refresh |
| Spending aggregated by category, account, or month |
| Combined 5-API call in parallel |
| Multi-month trend analysis |
By default, transactions return a compact format with the fields that matter:
{
"id": "123456789012345678",
"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 and notes are included only when present. Set verbose=True on any tool for the full API response with all metadata.
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)
Create a .env file (git-ignored):
MONARCH_EMAIL="your-email@example.com"
MONARCH_PASSWORD="your-password"
MONARCH_MFA_SECRET="YOUR_TOTP_SECRET_KEY"uv run pytest tests/ -v # unit tests (no creds needed)
uv run pytest tests/test_integration.py -v # integration tests (needs .env)
uv run scripts/health_check.py # quick API connectivity checkRun all checks locally (same as GitHub Actions CI):
uv run python scripts/ci.pyCut a release with the /release flow (bump version in pyproject.toml → commit → tag vX.Y.Z → push → gh release create). Publishing the GitHub release triggers .github/workflows/publish.yml, which builds and pushes to PyPI and the MCP Registry via OIDC trusted publishing — no API tokens are stored anywhere. The workflow injects the tag version into server.json automatically, so pyproject.toml is the only version field you bump by hand.
Tools for measuring and optimizing token usage across MCP sessions:
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: Monarch Money does not provide an official API. This server uses unofficial API access that requires your actual account credentials. Use with appropriate caution.
The server runs locally on your machine — your credentials live in your MCP client config and never pass through the LLM. Only the financial data you actually query is returned to the assistant.
Your credentials have full account access — treat them like passwords
The MFA secret (TOTP key) provides ongoing access
Session files in ~/.monarch-mcp/ contain auth tokens — keep them secure
Never commit .env or .mcp.json files to version control
This is an unofficial API — Monarch Money could change or restrict access at any time
This project started as a fork of colvint/monarch-money-mcp by @colvint. Thanks for the original implementation!
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.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jamiew/monarch-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
