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., "@monarchmoney-node 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.
Node.js/TypeScript library for accessing Monarch Money data.
Disclaimer: This project is unofficial and not affiliated with Monarch Money.
npm install @hakimelek/monarchmoneyRequires Node.js 18+ (uses native fetch and AbortSignal.timeout).
Related MCP server: Monarch Money MCP Server
import {
MonarchMoney,
EmailOtpRequiredException,
RequireMFAException,
} from "@hakimelek/monarchmoney";
const mm = new MonarchMoney();
try {
await mm.login("your@email.com", "password");
} catch (e) {
if (e instanceof EmailOtpRequiredException) {
// Monarch sent a verification code to your email
const code = await promptUser("Enter the code from your email:");
await mm.submitEmailOtp("your@email.com", "password", code);
} else if (e instanceof RequireMFAException) {
// TOTP-based MFA is enabled on the account
await mm.multiFactorAuthenticate("your@email.com", "password", "123456");
}
}
// Fetch data — fully typed responses
const { accounts } = await mm.getAccounts();
console.log(accounts[0].displayName, accounts[0].currentBalance);Monarch's API requires email verification (OTP) for new devices/sessions, even when MFA is disabled. The library handles this with distinct exception types so your app can respond appropriately.
try {
await mm.login(email, password);
} catch (e) {
if (e instanceof EmailOtpRequiredException) {
// A code was sent to the user's email — prompt them for it
const code = await yourApp.promptForEmailCode();
await mm.submitEmailOtp(email, password, code);
}
}await mm.login("email", "password", {
mfaSecretKey: "YOUR_BASE32_SECRET",
});The MFA secret is the "Two-factor text code" from Settings > Security > Enable MFA in Monarch Money.
After a successful login (including email OTP), you can save the token to avoid re-authenticating on every run:
// Save token after login
mm.saveSession(); // writes to .mm/mm_session.json (mode 0o600)
// Next time, login() loads the saved session automatically
await mm.login(email, password); // uses saved token, no network call
// Or pass the token directly (skip login entirely)
const mm = new MonarchMoney({ token: "your-saved-token" });mm.saveSession(); // save to disk
mm.loadSession(); // load from disk
mm.deleteSession(); // remove the file
mm.setToken("..."); // set token programmaticallyawait mm.interactiveLogin(); // prompts for email, password, email OTP or MFA codeAll methods return typed responses. Hover over any method in your editor for full JSDoc and type information.
Method | Returns | Description |
|
| All linked accounts |
|
| Available account types/subtypes |
|
| Daily balances (default: last 31 days) |
|
| Snapshots by type ( |
|
| Aggregate net value over time |
|
| Securities in a brokerage account |
|
| Daily balance history |
|
| Linked institutions |
|
| Budgets with actuals (default: last month → next month) |
|
| Plan status (trial, premium, etc.) |
|
| Aggregate summary |
|
| Transactions with full filtering |
|
| All matching transactions (auto-paginates) |
|
| Async generator yielding pages |
|
| All categories |
|
| Category groups |
| typed response | Single transaction detail |
| typed response | Splits for a transaction |
|
| All tags |
|
| Cashflow by category, group, merchant |
|
| Income, expense, savings, savings rate |
|
| Upcoming recurring transactions |
|
| Check refresh status |
Method | Returns | Description |
|
| Create manual account |
|
| Update account settings/balance |
|
| Delete account |
|
| Start refresh (non-blocking) |
|
| Refresh and poll until done |
|
| Create transaction |
|
| Update transaction |
|
| Delete transaction |
|
| Manage splits |
|
| Create category |
|
| Delete category |
|
| Bulk delete |
|
| Create tag |
|
| Set tags on transaction |
|
| Set/clear budget |
|
| Upload balance history CSV |
import {
MonarchMoneyError, // base class for all errors
EmailOtpRequiredException, // email verification code needed — call submitEmailOtp()
RequireMFAException, // TOTP MFA required — call multiFactorAuthenticate()
LoginFailedException, // bad credentials or auth error (includes .statusCode)
RequestFailedException, // API/GraphQL failure (includes .statusCode, .graphQLErrors)
} from "@hakimelek/monarchmoney";
try {
await mm.login(email, password);
} catch (e) {
if (e instanceof EmailOtpRequiredException) {
// e.code === "EMAIL_OTP_REQUIRED"
// Prompt user for the code sent to their email
const code = await getCodeFromUser();
await mm.submitEmailOtp(email, password, code);
} else if (e instanceof RequireMFAException) {
// e.code === "MFA_REQUIRED"
// Prompt for TOTP code or use mfaSecretKey
} else if (e instanceof LoginFailedException) {
// e.code === "LOGIN_FAILED", e.statusCode
console.error("Login failed:", e.message);
}
}
try {
await mm.getAccounts();
} catch (e) {
if (e instanceof RequestFailedException) {
console.error(e.statusCode); // HTTP status, if applicable
console.error(e.graphQLErrors); // GraphQL errors array, if applicable
console.error(e.code); // "HTTP_ERROR" | "REQUEST_FAILED"
}
}const mm = new MonarchMoney({
sessionFile: ".mm/mm_session.json", // session file path
timeout: 10, // API timeout in seconds
token: "pre-existing-token", // skip login
retry: {
maxRetries: 3, // retry on 429/5xx (default: 3, set 0 to disable)
baseDelayMs: 500, // base delay with exponential backoff + jitter
},
rateLimit: {
requestsPerSecond: 10, // token-bucket throttle (default: 0 = unlimited)
},
});
mm.setTimeout(30); // change timeout laterRetry automatically handles transient failures (429 Too Many Requests, 500, 502, 503, 504) with exponential backoff and jitter. The Retry-After header is respected on 429 responses.
getTransactions() returns a single page. For large datasets, use the auto-pagination helpers:
// Async generator — yields one page at a time (memory-efficient)
for await (const page of mm.getTransactionPages({ startDate: "2025-01-01", endDate: "2025-12-31" })) {
for (const tx of page) {
console.log(tx.merchant?.name, tx.amount);
}
}
// Or collect everything into a flat array
const all = await mm.getAllTransactions({
startDate: "2025-01-01",
endDate: "2025-12-31",
pageSize: 100, // transactions per page (default: 100)
});
console.log(`${all.length} total transactions`);Both methods accept the same filter options as getTransactions() (date range, category, account, tags, etc.).
Track account refresh progress with the onProgress callback:
await mm.requestAccountsRefreshAndWait({
timeout: 300,
delay: 10,
onProgress: ({ completed, total, elapsedMs }) => {
console.log(`${completed}/${total} accounts refreshed (${(elapsedMs / 1000).toFixed(0)}s)`);
},
});This package includes a built-in Model Context Protocol server with 30 tools, making your Monarch Money data accessible to AI assistants like Claude Desktop, Cursor, and any MCP-compatible client.
Get your Monarch Money auth token by logging in with the library (see Authentication) and saving mm.token.
Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):
{
"mcpServers": {
"monarch-money": {
"command": "npx",
"args": ["@hakimelek/monarchmoney"],
"env": {
"MONARCH_TOKEN": "your-token-here"
}
}
}
}Or run it directly:
MONARCH_TOKEN=your-token npx @hakimelek/monarchmoneyRead (18 tools): get_accounts, get_account_holdings, get_account_history, get_account_type_options, get_recent_account_balances, get_aggregate_snapshots, get_institutions, get_budgets, get_subscription_details, get_transactions, get_transactions_summary, get_transaction_details, get_transaction_categories, get_transaction_category_groups, get_transaction_tags, get_cashflow, get_cashflow_summary, get_recurring_transactions
Write (12 tools): create_transaction, update_transaction, delete_transaction, create_manual_account, update_account, delete_account, refresh_accounts, is_refresh_complete, set_budget_amount, create_transaction_tag, set_transaction_tags, create_transaction_category
Every tool has typed parameters with descriptions, so AI agents know exactly what arguments to pass.
src/
index.ts — public exports
client.ts — MonarchMoney class with all API methods
mcp.ts — MCP server (30 tools for AI agents)
errors.ts — error classes (MonarchMoneyError hierarchy)
endpoints.ts — API URL constants
queries.ts — all GraphQL query/mutation strings
types.ts — TypeScript interfaces for all API responsesnpm test # run tests once
npm run test:watch # run tests in watch mode
npm run test:coverage # run with coverage reportTests use Vitest and do not require real API credentials (fetch is mocked where needed).
Test the API connection (against the live api.monarch.com):
npm run build
# Login with email + password (will prompt for email OTP code if required)
MONARCH_EMAIL=your@email.com MONARCH_PASSWORD=yourpassword npm run test:connection
# Use a saved token (skips login)
MONARCH_TOKEN=your-token npm run test:connection -- --tokenSet these in a .env file for convenience (see .env.example).
How do I use this if I login to Monarch via Google?
Set a password on your Monarch account at Settings > Security, then use that password with this library.
Why does Monarch ask for an email code every time I login?
Monarch requires email verification for new/unrecognized devices. After login, save the session token with mm.saveSession() or store mm.token — subsequent runs will reuse it without re-authenticating.
There are several unofficial Monarch Money integrations. Here's how @hakimelek/monarchmoney stacks up.
@hakimelek/monarchmoney | monarch-money-api (pbassham) | monarchmoney (keithah) | monarchmoney (hammem) | |
Platform | Node.js / TypeScript | Node.js / JavaScript | Node.js / TypeScript | Python |
npm weekly downloads | — | ~440 | ~130 | N/A (pip: ~103K/mo) |
Runtime deps | 1 (speakeasy) | 5 | 7 | 3 |
TypeScript types | Full (every response) | None | Yes | N/A |
Email OTP flow | Yes | No | No | No |
MFA / TOTP | Yes | Yes | Yes | Yes |
Session persistence | Yes (0o600 perms) | Yes | Yes (AES-256) | Yes |
Interactive CLI login | Yes | Yes | Yes | Yes |
HTTP client | Native | node-fetch | node-fetch + graphql-request | aiohttp |
Error hierarchy | 4 typed exceptions | Generic throws | Generic throws | 1 exception |
Read methods | 20 | 15 | ~20 | ~16 |
Write methods | 14 | 9 | ~12 | ~10 |
Rate limiting | Yes | No | Yes | No |
Retry with backoff | Yes | No | Yes | No |
Auto-pagination | Yes | No | No | No |
Dual CJS + ESM | Yes | No | Yes | No |
Refresh progress events | Yes | No | No | No |
Built-in MCP server | Yes (30 tools) | No | No | No |
Minimal footprint. One runtime dependency vs 5-7 in the JS/TS alternatives. Native fetch means zero HTTP polyfills on Node 18+.
Email OTP support. Monarch now requires email verification for unrecognized devices, even when MFA is off. This is the only Node.js library that handles the full EmailOtpRequiredException → submitEmailOtp() flow. Without it, automated scripts break on first login from a new environment.
Typed everything. Every API response has a dedicated TypeScript interface — 50+ exported types covering accounts, transactions, holdings, cashflow, budgets, recurring items, and mutations. The monarch-money-api package has no types at all.
Structured error handling. Four distinct exception classes (LoginFailedException, RequireMFAException, EmailOtpRequiredException, RequestFailedException) with error codes and status codes. Competitors throw generic errors or strings.
Broader write coverage. Includes updateTransaction(), setBudgetAmount(), uploadAccountBalanceHistory(), getCashflow(), getCashflowSummary(), and getRecurringTransactions() — all missing from monarch-money-api.
Clean, flat API. One class, direct methods, no sub-objects or verbosity levels to learn. Import MonarchMoney, call methods, get typed results.
Contributions welcome. Please ensure TypeScript compiles cleanly (npm run build) and tests pass (npm test).
MIT
Create a new manual account (not linked to a bank).
| Name | Required | Description | Default |
|---|---|---|---|
| account_name | Yes | Display name for the account | |
| account_type | Yes | Account type (e.g. 'depository', 'credit', 'investment') | |
| account_sub_type | Yes | Account subtype (e.g. 'checking', 'savings', 'credit_card') | |
| is_in_net_worth | Yes | Whether to include in net worth calculations | |
| account_balance | No | Starting balance |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It only states 'create a new manual account' but does not disclose any side effects, required permissions, constraints (e.g., duplicate names), or what happens upon creation.
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 of 10 words, highly concise and front-loaded with the core purpose. It could include a bit more context without being verbose, but it avoids unnecessary details.
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 creation tool with 5 parameters and no output schema, the description is incomplete. It does not explain what a manual account is, the return value, or any post-creation behavior (e.g., whether the account is immediately usable).
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?
All 5 parameters have descriptions in the input schema (100% coverage), so the description adds no additional meaning. Baseline 3 is appropriate as the schema already documents each parameter adequately.
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 the verb 'create', the resource 'manual account', and explicitly differentiates it from bank-linked accounts. This distinguishes it from siblings like update_account, delete_account, and create_transaction.
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 vs alternatives. While the purpose implies it's for manual accounts, there's no mention of when not to use it or which sibling to use for bank-linked accounts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new transaction in a specific account.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Transaction date in YYYY-MM-DD format | |
| account_id | Yes | The account ID to create the transaction in | |
| amount | Yes | Transaction amount (positive = income, negative = expense) | |
| merchant_name | Yes | Merchant or payee name | |
| category_id | Yes | Category ID for the transaction | |
| notes | No | Optional notes | |
| update_balance | No | Whether to update the account balance |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits but fails to mention side effects like account balance updates (implied by the update_balance parameter), required permissions, or return behavior. The tool creates a record, but the description omits critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, complete sentence with no superfluous words. It efficiently conveys the core 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 7 parameters (5 required) and no output schema, the description should explain return values and behavior of flags like update_balance. It does not, leaving the agent without enough context to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema adequately documents all parameters. The description adds no new semantics beyond the schema, but also does not mislead. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create') and the resource ('transaction') with a qualifier ('in a specific account'), distinguishing it from update and delete tools. However, it does not elaborate on the nature of transactions (e.g., financial), leaving some ambiguity.
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 update_transaction or delete_transaction. The description merely states what it does, offering no contextual usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new transaction category within a category group.
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | The category group ID to add the category to | |
| name | Yes | Category name | |
| icon | No | Category icon emoji |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'create' without disclosing side effects, idempotency, or behavior on duplicate names. The burden is on the description but it adds minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no extraneous words. Front-loaded and efficient.
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 3 parameters, no output schema, and no annotations, the description is too minimal. It should explain that group_id must reference an existing category group, or note that icon is optional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description does not add any meaning beyond schema; it merely restates that the category is created within a group but doesn't elaborate on parameters like icon or group_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and the resource (transaction category) with context (within a category group). It effectively distinguishes from siblings like 'create_transaction' and 'create_transaction_tag'.
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, nor any prerequisites like that the category group must exist. The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new tag for categorizing transactions.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Tag name | |
| color | Yes | Tag color (hex code, e.g. '#FF5733') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'Create', implying mutation without details on idempotency, error behavior (e.g., duplicate names), or permissions. Minimal disclosure.
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 with no wasted words. It is appropriately concise for a simple tool, though it could benefit from slightly more structure or clarity.
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 only 2 simple parameters and no output schema, the description is adequate but does not mention constraints like uniqueness. It covers the basic purpose but lacks completeness on potential pitfalls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% as both parameters (name, color) have descriptions. The tool description adds no additional semantic value beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'create' and the resource 'tag for categorizing transactions'. It effectively distinguishes from sibling tools like 'create_transaction_category' which creates categories, not tags.
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 such as 'set_transaction_tags' or 'create_transaction_category'. The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an account by ID. This is irreversible.
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes | The account ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses irreversibility, a critical behavioral trait. However, given the absence of annotations, it fails to mention other key behaviors such as whether deletion is cascading or requires specific permissions.
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 with two clear, front-loaded sentences. Every word serves a purpose with no redundancy.
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 tool with a single parameter and no output schema, the description is largely complete. It explains the action and irreversibility, though it could mention impact on related data or dependencies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal value beyond what the schema already provides. The phrase 'by ID' reinforces the parameter's purpose but does not elaborate on format or constraints.
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 ('Delete') and the resource ('an account') with the unique identifier ('by ID'). It effectively distinguishes this destructive tool from sibling tools like 'update_account' or 'create_manual_account'.
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 notes irreversibility but does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'update_account' to deactivate instead). No prerequisites or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a transaction by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | The transaction ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description lacks disclosure on behavioral traits like permanence, idempotency, cascading effects, or permission requirements. Minimal beyond the basic action.
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?
Single sentence, five words, no waste. Front-loads the key action. Efficient for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param, no output schema, no annotations), the description is functional but lacks behavioral context (e.g., whether deletion is reversible, what happens to associated tags). Could be more 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?
Schema coverage is 100% for the single parameter. The description adds no extra meaning beyond the schema's description of 'transaction_id'. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('delete'), the resource ('transaction'), and the method ('by ID'). It distinguishes from sibling tools like 'update_transaction' or 'create_transaction'.
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 (e.g., updating to deactivate instead). No prerequisites mentioned (e.g., transaction must exist, effect on related data).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get daily balance history for a specific account.
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes | The account ID to fetch history for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It correctly implies a read-only operation ('Get'), but omits critical details such as data range (e.g., how far back history goes) or output format. This is adequate for a simple retrieval but lacks depth.
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 of 7 words with no filler. Every word is necessary, and it is front-loaded with the action and resource.
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 single parameter and no output schema, the description covers the basic purpose. However, it fails to describe return values (e.g., what fields are in the history records) or any limitations like date range or pagination. This incomplete specification may require agents to infer expected output.
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 schema description coverage is 100%, so the baseline is 3. The tool description adds no extra meaning beyond the schema's 'The account ID to fetch history for'. No format or constraints are specified for the account_id 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 verb 'Get' and the resource 'daily balance history for a specific account', making the tool's purpose unambiguous. It distinguishes itself from sibling tools like get_account_holdings (holdings vs. history) and get_recent_account_balances (recent vs. daily history).
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 does not provide explicit when-to-use instructions or alternatives. While the tool name and context imply usage for historical daily balance queries, no guidance is given on when not to use it or how it compares to similar tools like get_recent_account_balances.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get investment holdings (securities, stocks, ETFs) for a specific brokerage or investment account.
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes | The account ID to fetch holdings for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose behavioral traits such as read-only nature, rate limits, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words, front-loaded with 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?
No output schema, and description lacks details about return structure (e.g., list of securities with quantities, prices). Incomplete for a holdings tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides description for account_id, and description doesn't add meaning beyond that. Baseline score for high 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?
Clearly states verb 'Get', resource 'investment holdings', and specifies account type (brokerage or investment). Distinguishes from siblings like 'get_accounts'.
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 vs alternatives. No mention of prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all linked bank, credit, investment, and manual accounts with current balances.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that balances are returned, but does not mention data freshness, whether accounts are filtered (e.g., active only), or any performance implications. It is fairly transparent for a simple read operation but lacks depth.
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 with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters. The description mentions balances, but lacks detail on the return format (e.g., list of account objects). Since there is no output schema, a touch more detail would be beneficial, but it's acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema description coverage is 100%. The description does not need to add parameter details as none exist. Baseline is 4 due to zero parameters and full 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 action (get all linked accounts) and includes specific account types (bank, credit, investment, manual) and current balances. It distinguishes from sibling tools like get_account_history and get_account_holdings which have narrower scopes.
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 retrieving a broad set of accounts, but does not explicitly state when to use this tool versus alternatives like get_recent_account_balances or get_aggregate_snapshots. No exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all available account types and subtypes (useful when creating manual accounts).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes a simple read operation ('Get all available account types and subtypes') but lacks details such as whether the data is cached, requires authentication, or has pagination. For a tool with zero parameters, the description adds minimal behavioral context beyond the name, but it is not misleading.
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 immediately states the action and the resource. It includes a parenthetical note about utility, which is relevant and non-redundant. Every word earns its place, and there is no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and no annotations, the description is minimal. It explains the 'what' and a key use case, but does not elaborate on the structure of the response or how the returned types/subtypes map to other tools. For a simple list retrieval, this is adequate but not comprehensive.
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 no parameters, so schema description coverage is 100%. The description adds no parameter-related information, which is acceptable as there are no parameters to document. According to the rubric, a score of 3 is appropriate when the schema coverage is high and the description does not need to compensate.
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 'Get all available account types and subtypes', which is a specific verb ('Get') and resource ('account types and subtypes'). It also notes the utility 'when creating manual accounts', which helps distinguish it from sibling tools like 'create_manual_account'. This clarity aids an AI agent in understanding the tool's primary function.
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 explicitly states the tool is 'useful when creating manual accounts', providing a clear context for use. However, it does not mention when not to use it or list alternative tools for similar purposes. Given the sibling tools include many getters, but none that retrieve account types, this is a minor omission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get daily aggregate net worth across all accounts over time.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date in YYYY-MM-DD format | |
| end_date | No | End date in YYYY-MM-DD format | |
| account_type | No | Filter by account type |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description discloses that it returns daily aggregates across all accounts, but lacks information on data freshness, performance implications, or whether date range is required.
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?
Single sentence of 8 words, front-loaded with key action and resource. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers basic function but omissions: no mention of return format, default date behavior, or relationship to similar tools. With no output schema, more detail on response is warranted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. Description does not add additional meaning beyond what the schema already provides for start_date, end_date, and account_type.
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?
Description clearly states the verb 'Get', the resource 'daily aggregate net worth', and scope 'across all accounts over time'. It distinguishes from sibling tools like get_accounts or get_cashflow.
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?
Description implies usage for overall net worth trends but does not explicitly state when to use this tool vs alternatives like get_cashflow or get_account_history. No when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get budgets with actual spending amounts. Defaults to previous month through next month.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date in YYYY-MM-DD format | |
| end_date | No | End date in YYYY-MM-DD format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states it returns spending amounts but does not disclose read-only nature, error handling, or any side effects. Minimal 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?
Two short sentences with no wasted words. Front-loaded with primary action and adds essential default behavior succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with two optional parameters, description covers default behavior. Could mention response format or that budgets include actual spending, but adequate given tool complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions. Description adds valuable context that tool defaults to previous month through next month when no dates given, enhancing semantic understanding beyond 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?
Description clearly states 'Get budgets with actual spending amounts' which is a specific verb and resource. It distinguishes from siblings like set_budget_amount, but could be more explicit about what budgets include.
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?
Only mentions default date range; no guidance on when to use this tool versus alternatives or when not to use it. Lacks explicit context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get cashflow data grouped by category, category group, and merchant. Defaults to current month.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date in YYYY-MM-DD format | |
| end_date | No | End date in YYYY-MM-DD format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It mentions the data is grouped and defaults to the current month, which adds useful context. However, it does not disclose whether the operation is read-only, whether there are any side effects, limits, or how errors are handled. For a non-annotated tool, this is moderately transparent.
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, consisting of two short sentences that front-load the key action and grouping details. Every word provides value, and there is no redundancy.
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 presence of several sibling tools and no output schema, the description adequately covers the input and default behavior. However, it does not describe the structure of the returned data (e.g., fields available at each grouping level). For a data retrieval tool, this omission reduces completeness.
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 100% description coverage, but the description adds significant value by stating that the tool defaults to the current month when parameters are omitted. This clarifies the behavior beyond the schema definitions, which only specify the format.
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 'Get', the resource 'cashflow data', and specifies it is grouped by category, category group, and merchant. This level of detail distinguishes it from sibling tools like 'get_cashflow_summary' which likely provides a summary, and 'get_transactions' which returns raw data. The default to current month adds clarity.
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 grouped cashflow data but lacks explicit guidance on when to use this tool versus alternatives such as 'get_cashflow_summary', 'get_transactions', or other related tools. No when-not-to-use conditions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get cashflow summary: total income, expenses, savings, and savings rate. Defaults to current month.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date in YYYY-MM-DD format | |
| end_date | No | End date in YYYY-MM-DD format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states 'Get' implying read-only, but does not explicitly confirm no side effects, no destructive actions, or any rate limits. For a read operation, this is a minimal disclosure but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core purpose and a key default behavior. No unnecessary words; every sentence earns its place. Perfectly sized for quick comprehension.
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 output schema, the description lists the returned metrics (income, expenses, savings, savings rate), providing adequate context. However, it does not mention whether data is aggregated across accounts or by category, nor does it address pagination or date-range validation. Siblings like get_cashflow might offer more detail, but this tool's description suffices for its likely limited 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?
Although the input schema already covers start_date and end_date with descriptions, the description adds value by stating 'Defaults to current month', clarifying default behavior when parameters are omitted. This compensates for the schema's lack of default values and aids parameter usage.
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 gets a cashflow summary with specific metrics (total income, expenses, savings, savings rate). It distinguishes from similar tools like get_cashflow or get_transactions_summary by naming output fields. However, it could clarify the scope (e.g., all accounts or selected) and is slightly vague about what 'cashflow summary' includes beyond the listed items.
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 mentions defaulting to the current month, implying optional date parameters, but provides no guidance on when to use this tool versus siblings like get_cashflow, get_transactions_summary, or get_budgets. No when-not-to-use or alternative suggestions are given.
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 and their connection status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It implies a read-only operation via 'Get', but does not explicitly state non-destructiveness, authentication needs, or rate limits. Additional context about 'linked' and 'connection status' would improve 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?
A single, front-loaded sentence with no unnecessary words. It directly conveys the purpose without fluff. 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 simple, no-parameter tool, the description is adequate but incomplete. It lacks details about the output format, what 'connection status' entails, and any potential nuances (e.g., caching, data freshness). Given no output schema, the description should provide some expectation of the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema description coverage is 100% (no undefined params). The description does not need to add parameter semantics since none exist. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), the resource ('linked financial institutions'), and the specific aspect ('their connection status'). It effectively distinguishes from sibling tools like get_accounts or get_transactions by focusing on institutions and their status.
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 (e.g., get_accounts). It does not indicate that it is a no-parameter, read-only operation or when it should be prioritized over other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get daily account balances for a date range. Defaults to last 31 days.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date in YYYY-MM-DD format. Defaults to 31 days ago. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the read-only nature and date-range constraint but omits details about data freshness, pagination, permissions, or what constitutes 'balances' (e.g., pending entries). This lack of depth leaves the agent underinformed.
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, front-loaded sentence that contains no filler. Every word serves a purpose: verb, resource, scope, and default behavior.
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 optional param, no output schema, no annotations), the description is minimally adequate. However, it fails to describe the return format (e.g., list of daily balances per account) or how to interpret the results, which would help the agent use the output properly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the 'start_date' parameter and its default. The tool description echoes this default ('last 31 days'), adding no new semantic value 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 clearly states the action (get), resource (daily account balances), and scope (date range). It distinguishes from siblings like 'get_accounts' (current balances) and 'get_account_history' (transactions), but does not explicitly contrast with them.
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 when to use (need daily balances over a range) and provides a default, but offers no explicit guidance on when not to use or alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get upcoming recurring transactions (subscriptions, bills). Defaults to current month.
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date in YYYY-MM-DD format | |
| end_date | No | End date in YYYY-MM-DD format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavioral traits. It only notes default behavior (current month) but does not mention whether it is read-only, pagination limits, or other side effects. The update description is minimal.
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 immediately conveys the tool's purpose and default behavior. No extraneous words or redundant information. It is optimally concise and front-loaded.
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 lack of an output schema, the description should hint at what the response contains (e.g., list of transactions). It does not. Additionally, it does not differentiate from similar sibling tools like 'get_subscription_details'. The description is too minimal to be fully contextually 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?
Schema description coverage is 100%, so the schema already documents both parameters (start_date, end_date) with format hints. The description adds no additional parameter meaning beyond stating the default timeframe. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves upcoming recurring transactions (subscriptions, bills). The verb 'get' and resource 'recurring transactions' are explicit, and it distinguishes from siblings like 'get_transactions' by specifying 'upcoming recurring'.
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 mentions defaulting to the current month, which implies when no dates are provided, but it does not explicitly state when to use this tool over alternatives like 'get_subscription_details' or 'get_transactions'. No when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Monarch Money subscription status (trial, premium, plan info).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It indicates a read operation ('Get') but does not disclose any potential limitations, rate limits, or behavior when there is no subscription.
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 sentence of 10 words, no redundancy, and front-loaded. 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 simple read operation with no output schema, the description adequately sets expectations about the content (subscription status, plan info). Minor gap: no mention of return format or error cases.
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 zero parameters and 100% schema coverage, the description adds value by specifying the type of information returned (trial, premium, plan info), which the empty schema cannot convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves Monarch Money subscription status, including trial, premium, and plan info. The verb 'Get' and resource 'subscription status' are specific and distinguish it from sibling getter 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?
No guidance on when to use this tool vs alternatives or when not to use it. Although it's a simple getter, explicit context would improve selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all transaction categories configured in the account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, pagination, ordering, or any constraints. The description is too minimal to inform the agent about side effects or limits.
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, clear sentence that is front-loaded and contains no extraneous information. It is appropriately sized for a tool with no 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?
The tool has no output schema, so the description could hint at the response format (e.g., list of category names or objects). It is adequate but lacks details on what the return values represent.
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 zero parameters, so no additional semantics are needed. The baseline for 0 parameters is 4, and the description does not need to add 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 uses a specific verb 'Get' and resource 'transaction categories', clearly distinguishing it from siblings like 'get_transaction_category_groups' or 'get_transaction_tags'.
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 such as 'get_transaction_category_groups' or 'get_transaction_tags'. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all category groups (e.g. Income, Food & Drink, Housing).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states it gets category groups, but no disclosure of behavioral aspects like authentication requirements, rate limits, or side effects. Since it's a simple retrieval, the minimal score is justified.
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?
Single sentence, front-loaded with action verb, no redundant words. Perfectly concise for the tool's simplicity.
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 simple retrieval tool, description is adequate. Could mention return format (list of strings) but not essential. Lacks output schema but that's not required per rules.
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%. Description adds value beyond schema by providing concrete examples of category groups, clarifying what kind of data is returned.
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?
Description clearly states verb 'Get' and resource 'all category groups' with concrete examples (Income, Food & Drink, Housing). This distinguishes it from sibling tools like get_transaction_categories (categories, not groups) and other retrieval 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?
No guidance on when to use this tool versus alternatives (e.g., get_transaction_categories), no context about prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details for a single transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | The transaction ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral aspects. It only states 'full details' without specifying what those details include (e.g., tags, categories), nor does it address side effects, permissions, or rate limits.
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, clear sentence that is front-loaded and contains no unnecessary words.
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 single parameter, lack of output schema, and sibling tools for transaction details, the description provides minimal context. It fails to clarify what 'full details' entails, leaving ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the single parameter 'transaction_id' described as 'The transaction ID'. The description adds no extra meaning beyond this, meeting the baseline but not exceeding 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 it retrieves full details for a single transaction, effectively distinguishing it from sibling tools like 'get_transactions' (likely multi-transaction) and 'get_transactions_summary' (summary only).
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 use when needing full details of a specific transaction, but lacks explicit guidance on when to or not to use this tool versus alternatives, such as when a summary or list is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and filter transactions with pagination. Returns up to limit transactions at a time.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max transactions to return (default: 100) | |
| offset | No | Pagination offset (default: 0) | |
| start_date | No | Start date in YYYY-MM-DD format (requires end_date) | |
| end_date | No | End date in YYYY-MM-DD format (requires start_date) | |
| search | No | Search text to filter by merchant name, notes, etc. | |
| category_ids | No | Filter by category IDs | |
| account_ids | No | Filter by account IDs | |
| tag_ids | No | Filter by tag IDs |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses pagination behavior (limit, offset) and filtering capability but lacks details on ordering, default behavior, rate limits, or side effects. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences are front-loaded with the core purpose. No unnecessary words or information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 optional parameters, no output schema, and no annotations, the description covers basic functionality but omits details on default sorting, response structure, and behavior with no filters. Adequate but could be more 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?
Schema coverage is 100% with all parameters documented. The description adds little beyond 'Search and filter transactions with pagination' which is already implied by the parameter names and descriptions. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Search and filter), resource (transactions), and mechanism (pagination). It distinguishes from sibling tools like get_transaction_details (single transaction) and get_transactions_summary (summary).
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 searching/filtering transactions but does not explicitly state when to use this tool vs. siblings like get_transaction_details or get_transactions_summary. No when-not or alternative guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregate transaction summary: totals, averages, counts, income, expenses.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It implies a read-only operation but does not confirm idempotency, data freshness, or any potential side effects. For a tool that likely queries aggregated data, this lack of detail is a gap.
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 concise sentence that efficiently communicates the tool's core purpose and key outputs. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description hints at the return fields, it does not specify the output structure or format, especially given the lack of an output schema. Among many sibling summary tools, a more detailed explanation of the summary schema would improve completeness. The current description is adequate but leaves ambiguity.
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 zero parameters with 100% coverage, so the description does not need to explain parameters. However, it adds value by describing the nature of the summary output (totals, averages, etc.), which compensates for the lack of output schema. A score of 4 is appropriate as it goes 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 clearly states the tool's action ('Get aggregate transaction summary') and explicitly lists the components (totals, averages, counts, income, expenses), making it easy to understand what the tool does. It distinguishes itself from sibling tools like get_transactions (which returns raw transactions) and get_cashflow (which focuses on cash flow) by emphasizing aggregation.
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_cashflow_summary or get_aggregate_snapshots. Users must infer from the name and sibling context, but without explicit usage directions, the risk of misselection remains high.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all tags configured in the account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description accurately reflects a read operation. It does not disclose potential details like authentication requirements or response format, but for a simple retrieval tool, this is acceptable.
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?
Description is a single, front-loaded sentence that conveys the purpose efficiently with no wasted words.
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 no parameters, no output schema, and is a straightforward retrieval, the description is fully adequate for an agent to understand its purpose and use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema description coverage is 100% (vacuously). Per guidelines, 0 parameters earns a baseline of 4. The description adds no param-specific details as none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves all tags configured in the account. Verb 'get' and resource 'tags' are specific, and it is distinct from sibling tools like 'create_transaction_tag' and 'set_transaction_tags'.
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 or alternatives. However, the tool is a simple getter, and the context implies it should be used when a list of all tags is needed. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a previously started account refresh has completed.
| Name | Required | Description | Default |
|---|---|---|---|
| account_ids | No | Account IDs to check. Omit to check all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It states the check operation but does not mention what happens if no refresh was started, whether it's idempotent, or rate limits. Adequate for a simple read operation but lacks depth.
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?
Single sentence, no extraneous words, front-loaded with the essential 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?
No output schema and no description of return value (e.g., boolean or status object). For a check tool, the outcome is critical. The description is too minimal for complete understanding.
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 covers 100% of parameters with good description. Description adds minimal value beyond schema, just indicating the context of 'previously started account refresh'.
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 'check' and the specific resource 'whether a previously started account refresh has completed'. It differentiates from sibling tools like refresh_accounts and get_accounts.
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 (e.g., polling after refresh_accounts). Does not specify prerequisites or conditions for checking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a refresh of account balances and transactions from linked institutions. Non-blocking.
| Name | Required | Description | Default |
|---|---|---|---|
| account_ids | Yes | Account IDs to refresh |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only mentions 'Non-blocking', omitting details like asynchronous processing, potential delays, or failure modes. More behavioral context is needed.
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?
Single concise sentence, front-loaded with the action verb, with no filler or repetition. Every word contributes to the core 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 low complexity, the description covers the basic purpose and non-blocking nature, but fails to mention the need to check is_refresh_complete or that refresh may take time, leaving gaps for effective 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 coverage is 100% with clear parameter description, and the description adds minimal context ('from linked institutions'), achieving baseline. No extra syntax or constraints are provided 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 clearly states the verb 'Trigger a refresh' and the resource 'account balances and transactions from linked institutions', distinguishing it from read-only sibling tools like get_accounts 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?
No guidance on when to use this tool versus alternatives, such as using is_refresh_complete to check status or avoiding duplicate triggers. The description lacks context for proper invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or clear a budget amount for a category or category group.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Budget amount. Use 0 to clear. | |
| category_id | No | Category ID (provide this OR category_group_id, not both) | |
| category_group_id | No | Category group ID (provide this OR category_id, not both) | |
| start_date | No | Budget period start date in YYYY-MM-DD format | |
| apply_to_future | No | Whether to apply to future months |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'set or clear,' without detailing side effects, permissions, or whether changes apply retroactively. The apply_to_future parameter hints at recurring application, but the description does not elaborate. A mutation tool should disclose more 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 a single sentence of 13 words, front-loaded with the verb 'set or clear.' It is concise and contains no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, the description is too brief. It does not specify return values, error handling, or edge cases (e.g., amount=0). A mutate tool with multiple parameters requires more completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already provides meaning for each parameter. The description adds no additional semantic value beyond restating the tool's action. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (set or clear) and the resource (budget amount for a category or category group). It uses a specific verb-resource pair and is distinct from sibling tools, as no other tool sets budget amounts.
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 vs alternatives. The input schema mentions the mutual exclusivity of category_id and category_group_id, but the description does not explain when to set vs clear or provide context for choosing between category and group. The sibling tools are not directly competing, so usage is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set (replace) all tags on a transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | The transaction ID | |
| tag_ids | Yes | Tag IDs to set. Pass empty array to remove all tags. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates replacement behavior via the word 'replace', which is adequate. However, no annotations are provided, and the description does not address side effects, authorization requirements, or rate limits. For a mutation tool, more context would be beneficial.
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 with no wasted words. It is front-loaded and immediately conveys the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, and the description does not mention return values or error conditions. While the action is simple, mutating tools often benefit from noting expected outcomes (e.g., success indicator).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds no extra meaning beyond the schema. The schema already explains that tag_ids accepts an array and that an empty array removes all tags. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set (replace) all tags on a transaction' uses a specific verb and resource, clearly distinguishing it from siblings like create_transaction_tag (which adds a tag) and get_transaction_tags (which retrieves tags).
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 replacing all tags but does not explicitly state when to use this tool versus alternatives like add/remove individual tags via update_transaction or create_transaction_tag. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an account's settings (name, balance, visibility, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes | The account ID to update | |
| account_name | No | New display name | |
| account_balance | No | New balance | |
| include_in_net_worth | No | Whether to include in net worth | |
| hide_from_summary_list | No | Whether to hide from summary |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description only says 'Update', which implies mutation but does not disclose side effects, permission requirements, or whether changes are reversible. No behavioral traits beyond the basic action.
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?
Single sentence is concise but includes 'etc.' which adds vagueness. Could be slightly more precise without losing 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?
With 5 parameters and no output schema, the description lacks details on return values, side effects, or post-update state. Agent may need to guess what happens after update.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description loosely groups parameters as 'name, balance, visibility, etc.' but does not add significant meaning beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'account's settings', and lists example fields. It distinguishes from sibling tools like create_manual_account and delete_account by focusing on modification.
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 vs alternatives such as create_manual_account or update_transaction. No context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update fields on an existing transaction. Only provided fields are changed.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | The transaction ID to update | |
| category_id | No | New category ID | |
| merchant_name | No | New merchant name | |
| amount | No | New amount | |
| date | No | New date in YYYY-MM-DD format | |
| notes | No | New notes | |
| hide_from_reports | No | Whether to hide from reports | |
| needs_review | No | Whether to mark as needs review |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description is responsible for revealing behavioral traits. It states that only provided fields are changed, indicating a partial update, which is key. However, it lacks details on side effects, authorization requirements, or error behaviors. This is adequate but could be more informative.
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 very concise with two short sentences. Every word serves a purpose, and it is front-loaded with the core action. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters and no output schema or annotations, the description provides the essential update behavior but lacks details on return values, error scenarios, or prerequisites. It is sufficient for a simple update but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters having descriptions. The tool description does not add additional meaning beyond what the schema already provides. According to guidelines, when coverage is high, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update fields on an existing transaction' which specifies both the action (update) and the resource (existing transaction). This distinguishes it from siblings like 'create_transaction' and 'delete_transaction'.
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 that this tool is used for updates and indicates that only provided fields are changed. While it gives clear context for when to use it, it does not explicitly mention when not to use it or suggest alternatives for other operations such as creating or deleting transactions.
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. Dates show when Glama detected each change.
v0.3.1create_manual_accountcreate_transactioncreate_transaction_categorycreate_transaction_tagdelete_accountdelete_transactionget_account_historyget_account_holdingsget_account_type_optionsget_accountsget_aggregate_snapshotsget_budgetsget_cashflowget_cashflow_summaryget_institutionsget_recent_account_balancesget_recurring_transactionsget_subscription_detailsget_transaction_categoriesget_transaction_category_groupsget_transaction_detailsget_transaction_tagsget_transactionsget_transactions_summaryis_refresh_completerefresh_accountsset_budget_amountset_transaction_tagsupdate_accountupdate_transactionEvery tool targets a distinct resource and action. Even similar tools like get_transactions, get_transaction_details, and get_transactions_summary have clear differentiation in descriptions.
All tool names follow a consistent verb_noun pattern in snake_case, with standard CRUD verbs and a few specific verbs like refresh and is_refresh_complete.
30 tools is slightly above the typical 3-15 range, but the domain of personal finance management is broad and each tool serves a distinct purpose, justifying the count.
Core account and transaction operations are well-covered, but missing single account retrieval and update/delete operations for categories and tags create notable gaps.
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.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/hakimelek/monarchmoney-node'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
