Which integrations are available for this server?

Provides read-only audit and reconciliation workflows for a Firefly III ledger, including missing transaction detection, duplicate detection, uncategorized transaction summaries with category suggestions, and balance mismatch checks, without creating or modifying any financial data.

How do I use finance-reconcile-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@finance-reconcile-mcp Find missing transactions from the last 30 days." 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.

finance-reconcile-mcp

by nalyDzzz

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Hybrid

finance-reconcile-mcp

Read-only Model Context Protocol server for reconciling SimpleFIN Bridge bank data against a Firefly III ledger.

This project is for audit and reconciliation workflows. It does not create, edit, delete, categorize, merge, import, or otherwise mutate financial data in Firefly III.

Status

v0.3.0 focuses on category intelligence and reviewable proposals: local category rules, category suggestion confidence, and compact review plans from the latest audit. Matching heuristics, category suggestions, and account mapping should still be reviewed before trusting the output.

Related MCP server: Ogarni.AI MCP Server

Features

Read-only SimpleFIN and Firefly III connectors
Setup tools for discovering accounts, validating mappings, and saving local config
Missing transaction detection across mapped accounts
Stale account and balance mismatch checks
Duplicate transaction detection in Firefly III
Uncategorized transaction summaries with suggested category labels
Local category rules for remembering merchant-to-category suggestions
Stable fingerprints for repeat audit findings
Local ignored-finding and audit-history files
Review plans that turn the latest audit into manual, non-mutating proposed actions
Compact JSON responses designed for AI agents and MCP clients

Requirements

Node.js 20 or newer
A SimpleFIN Access URL
A Firefly III Personal Access Token

Recommended Setup: OpenClaw + npx

After this package is published to npm, users should not need to clone the repo. Register it as an OpenClaw MCP server with npx.

openclaw mcp set finance-reconcile '{
  "command": "npx",
  "args": ["-y", "finance-reconcile-mcp@latest"],
  "env": {
    "SIMPLEFIN_ACCESS_URL": "https://user:password@bridge.simplefin.org/simplefin",
    "FIREFLY_BASE_URL": "https://firefly.example.com",
    "FIREFLY_PAT": "your-firefly-token",
    "DEFAULT_LOOKBACK_DAYS": "30",
    "READONLY": "true"
  }
}'

OpenClaw stores outbound MCP server definitions with openclaw mcp set. See the OpenClaw MCP docs for the full command surface.

By default, the account map is stored at:

Linux/macOS: ~/.config/finance-reconcile-mcp/account-map.json
Windows: %APPDATA%\finance-reconcile-mcp\account-map.json

Set ACCOUNT_MAPPING_FILE only if you want a custom path.

Ignored findings and audit history default to:

~/.config/finance-reconcile-mcp/ignored-findings.json
~/.config/finance-reconcile-mcp/audit-history.json

Set IGNORED_FINDINGS_FILE or AUDIT_HISTORY_FILE only if you want custom local paths.

Category rules default to the user config directory:

Linux/macOS: ~/.config/finance-reconcile-mcp/category-rules.json
Windows: %APPDATA%\finance-reconcile-mcp\category-rules.json

Set CATEGORY_RULES_FILE only if you want a custom local path.

OpenClaw User Flow

Once the server is registered, ask OpenClaw:

Check the setup status for my finance reconciliation MCP server.

OpenClaw should call setup_get_status.

Then ask:

Suggest an account map for my SimpleFIN and Firefly accounts.

OpenClaw should call setup_suggest_account_map, then show you:

confidence-scored account matches
unmatched SimpleFIN accounts
unmatched Firefly III accounts
an account_map_json_draft

Review the draft. If it looks right, ask:

Save this account map for finance reconciliation.

OpenClaw can call setup_save_account_map with:

{
  "account_map": {
    "accounts": [
      {
        "simplefin_id": "simplefin-account-id",
        "simplefin_name": "CHASE TOTAL CHECKING (...1234)",
        "firefly_account_id": "7",
        "firefly_name": "Chase Checking"
      }
    ]
  },
  "overwrite": true,
  "confirm_write": true
}

setup_save_account_map only writes the local account-map.json config file. It never writes to Firefly III or SimpleFIN.

Then validate:

Validate my saved finance reconciliation account map.

OpenClaw should call setup_validate_account_map.

Finally, reconcile:

Find SimpleFIN transactions from the last 30 days that appear missing from Firefly.

OpenClaw should call reconcile_find_missing_transactions with:

{
  "days": 30
}

For category review, ask:

Suggest categories for my uncategorized Firefly transactions.

OpenClaw should call firefly_summarize_uncategorized. The server may use local category rules, but it never applies categories to Firefly III.

For a compact manual review queue, ask:

Create a review plan for my finance audit.

OpenClaw should call reconcile_prepare_review_plan after an audit has been run. Review-plan actions always include would_mutate_firefly: false and requires_manual_review: true.

Audit And Review Workflow

Run the compact audit first:

Run a compact finance reconciliation audit for the last 30 days.

The reconcile_run_audit tool returns status, summary, recommended_actions, since_last_audit, and top_findings. It also writes a compact local audit-history snapshot with active finding fingerprints. This local write never creates, edits, categorizes, merges, or deletes financial data in Firefly III or SimpleFIN.

Inspect full details when needed:

{
  "days": 30,
  "include_details": true
}

Ignore a finding after reviewing its fingerprint:

{
  "fingerprint": "missing_transaction:example",
  "type": "missing_transaction",
  "reason": "Known historical import gap"
}

Use setup_ignore_finding for that local ignore. Future audits exclude ignored findings from active counts by default. To inspect ignored findings alongside the audit:

{
  "days": 30,
  "include_ignored": true
}

Every successful audit compares active finding fingerprints with the previous local snapshot:

{
  "since_last_audit": {
    "new_findings": 0,
    "resolved_findings": 1,
    "unchanged_findings": 6
  }
}

Prepare a review plan from the latest local audit snapshot:

Create a review plan for my finance audit.

The reconcile_prepare_review_plan tool returns missing transaction review items, duplicate review items, category suggestion items, stale account review items, and balance mismatch review items. These are reviewable proposals only. They do not create transactions, apply categories, delete duplicates, merge transactions, or write to Firefly III.

Category Rules

Category rules are local memory for category suggestions. They are stored as JSON:

{
  "rules": [
    {
      "id": "category_rule:example",
      "match": "king soopers",
      "category": "Groceries",
      "created_at": "2026-05-14T12:00:00.000Z"
    }
  ]
}

Rules match normalized transaction descriptions and merchant names. Add a rule when you want future summaries and review plans to suggest the same category for a merchant:

{
  "match": "king soopers",
  "category": "Groceries"
}

Use setup_add_category_rule, setup_remove_category_rule, and setup_list_category_rules to manage this local file. These setup tools only write local config. They never mutate Firefly III or SimpleFIN.

Configuration

Environment variables:

SIMPLEFIN_ACCESS_URL=https://user:password@bridge.simplefin.org/simplefin
FIREFLY_BASE_URL=https://your-firefly.example.com
FIREFLY_PAT=your-personal-access-token
DEFAULT_LOOKBACK_DAYS=30
READONLY=true
MOCK_DATA=false
# Optional. Defaults to the user config directory.
# ACCOUNT_MAPPING_FILE=/absolute/path/to/account-map.json
# Optional. Defaults to ~/.config/finance-reconcile-mcp/ignored-findings.json
# IGNORED_FINDINGS_FILE=/absolute/path/to/ignored-findings.json
# Optional. Defaults to ~/.config/finance-reconcile-mcp/audit-history.json
# AUDIT_HISTORY_FILE=/absolute/path/to/audit-history.json
# Optional. Defaults to the user config directory.
# CATEGORY_RULES_FILE=/absolute/path/to/category-rules.json

Notes:

READONLY=false is rejected at startup.
MOCK_DATA=true runs deterministic fixtures and does not require SimpleFIN or Firefly credentials.
SIMPLEFIN_ACCESS_URL may be the SimpleFIN root Access URL or the /accounts URL.
SimpleFIN Access URLs usually contain credentials. Keep the full URL; the server sends those credentials as an HTTP Basic Auth header internally.
Do not commit .env or account-map.json.

CLI Checks

These commands do not start the MCP server and do not print secrets:

finance-reconcile-mcp --version
finance-reconcile-mcp --check-config

For a safe fixture check:

MOCK_DATA=true finance-reconcile-mcp --check-config

Get A SimpleFIN Access URL

Create a SimpleFIN token from SimpleFIN Bridge. The token is not the Access URL; it is a base64-encoded claim URL. Decode it, then make a POST request to the decoded URL. The response body is the Access URL to use for SIMPLEFIN_ACCESS_URL.

Cross-platform Node.js command:

node -e "const token = process.argv[1]; const url = Buffer.from(token, 'base64').toString('utf8'); fetch(url, { method: 'POST' }).then(async (r) => { if (!r.ok) throw new Error('HTTP ' + r.status); console.log(await r.text()); }).catch((e) => { console.error(e.message); process.exit(1); });" "PASTE_SIMPLEFIN_TOKEN_HERE"

PowerShell alternative:

$token = "PASTE_SIMPLEFIN_TOKEN_HERE"
$claimUrl = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($token))
$accessUrl = Invoke-RestMethod -Method Post -Uri $claimUrl
$accessUrl

The result should look roughly like:

https://user:password@bridge.simplefin.org/simplefin

Treat this URL like a secret. It contains read credentials for the SimpleFIN account feed.

Firefly III Token

Create a Personal Access Token in Firefly III and set it as FIREFLY_PAT. The server only uses read endpoints, but you should still treat the token as a secret.

Account Mapping

account-map.json connects SimpleFIN accounts to Firefly III accounts:

{
  "accounts": [
    {
      "simplefin_id": "optional-simplefin-id",
      "simplefin_name": "CHASE TOTAL CHECKING (...1234)",
      "firefly_account_id": "7",
      "firefly_name": "Chase Checking"
    }
  ]
}

Use simplefin_id when you know it. If you omit it, the server falls back to an exact SimpleFIN account name match.

Generic MCP Client Configuration

If your MCP client uses JSON config directly:

{
  "mcpServers": {
    "finance-reconcile": {
      "command": "npx",
      "args": ["-y", "finance-reconcile-mcp@latest"],
      "env": {
        "SIMPLEFIN_ACCESS_URL": "https://user:password@bridge.simplefin.org/simplefin",
        "FIREFLY_BASE_URL": "https://your-firefly.example.com",
        "FIREFLY_PAT": "your-personal-access-token",
        "DEFAULT_LOOKBACK_DAYS": "30",
        "READONLY": "true"
      }
    }
  }
}

For a custom account-map path, add:

{
  "ACCOUNT_MAPPING_FILE": "/absolute/path/to/account-map.json"
}

Tools

Setup:

setup_get_status shows configuration and account-map status.
setup_list_simplefin_accounts lists SimpleFIN accounts for account mapping. It fetches balances only, not transactions.
setup_list_firefly_accounts lists Firefly III asset/liability accounts for account mapping.
setup_suggest_account_map suggests an account-map.json draft by comparing SimpleFIN and Firefly III account names, currencies, and balances.
setup_validate_account_map validates an account-map object or the configured file, optionally checking live accounts.
setup_save_account_map writes the local account-map.json config file after confirm_write: true. It does not mutate financial data.
setup_list_category_rules lists local category suggestion rules.
setup_add_category_rule adds or updates a local category suggestion rule.
setup_remove_category_rule removes a local category suggestion rule.
setup_list_ignored_findings lists locally ignored finding fingerprints.
setup_ignore_finding writes a finding fingerprint to the local ignored-findings file.
setup_unignore_finding removes a finding fingerprint from the local ignored-findings file.

Reconciliation:

reconcile_run_audit runs the full audit without mutating financial systems. It returns compact output by default and writes a local audit-history snapshot.
reconcile_prepare_review_plan creates reviewable proposed actions from the latest audit snapshot. Every action is manual-review-only and has would_mutate_firefly: false.
reconcile_find_missing_transactions compares mapped SimpleFIN and Firefly III transactions and returns SimpleFIN transactions that appear missing from Firefly III.
reconcile_check_stale_accounts compares the latest transaction dates per mapped account.
reconcile_check_balance_mismatches compares SimpleFIN balances with Firefly III account balances.

Firefly III audit helpers:

firefly_find_possible_duplicates finds possible duplicate Firefly III transactions.
firefly_summarize_uncategorized groups uncategorized Firefly III transactions and suggests category labels without applying them.

Tool Examples

Run the compact audit:

{
  "days": 30
}

Limit compact output:

{
  "days": 30,
  "max_missing": 5,
  "max_duplicates": 5,
  "max_uncategorized_groups": 5
}

Inspect full audit details:

{
  "days": 30,
  "include_details": true
}

Show ignored findings in the audit output:

{
  "days": 30,
  "include_ignored": true
}

Create a review plan from the latest audit:

{}

Add a local category rule:

{
  "match": "king soopers",
  "category": "Groceries"
}

Ignore a reviewed finding locally:

{
  "fingerprint": "duplicate_group:example",
  "type": "duplicate_group",
  "reason": "Reviewed and accepted duplicate-looking transfer split"
}

Find missing transactions over the default lookback window:

{}

Find missing transactions over 30 days:

{
  "days": 30
}

Find missing transactions for one mapped account:

{
  "days": 30,
  "account": "Chase Checking"
}

Use a fixed date range:

{
  "start_date": "2026-04-01",
  "end_date": "2026-04-30"
}

From Source

Use this path for development or until the package is published to npm.

git clone <repo-url>
cd finance-reconcile-mcp
npm install
cp .env.example .env
npm run build
npm start

On Windows PowerShell:

Copy-Item .env.example .env

For a source checkout, you can point OpenClaw at the built file:

openclaw mcp set finance-reconcile '{
  "command": "node",
  "args": ["/absolute/path/to/finance-reconcile-mcp/dist/index.js"],
  "cwd": "/absolute/path/to/finance-reconcile-mcp",
  "env": {
    "SIMPLEFIN_ACCESS_URL": "https://user:password@bridge.simplefin.org/simplefin",
    "FIREFLY_BASE_URL": "https://firefly.example.com",
    "FIREFLY_PAT": "your-firefly-token",
    "READONLY": "true"
  }
}'

Development

npm run dev
npm run typecheck
npm test
npm run build

npm pack and npm publish run npm run build automatically through the prepack script.

Release Checklist

npm version minor or npm version patch
git push origin main --follow-tags
npm publish
npm view finance-reconcile-mcp version

Mock Mode

Set MOCK_DATA=true to run against deterministic fixtures instead of real HTTP connectors. The fixture set includes one missing transaction, one duplicate Firefly transaction group, one stale account, one balance mismatch, and uncategorized transactions.

Example MCP client env:

{
  "MOCK_DATA": "true",
  "READONLY": "true"
}

Then call reconcile_run_audit with { "days": 30 }.

Matching Design

Transactions are normalized into a shared internal type before matching. Account mapping is required. Matching uses a score from 0 to 1:

signed amount exact match: high weight
posted date proximity within plus or minus 2 days: high weight
description similarity: medium weight
shared external transaction ID: immediate high confidence

The server masks source account and transaction identifiers in returned JSON where possible and never logs secrets.

Troubleshooting

SimpleFIN URL Includes Credentials

SimpleFIN Access URLs usually look like https://user:password@.../simplefin. Keep that full URL in SIMPLEFIN_ACCESS_URL; the server strips the credentials from the request URL and sends them as an HTTP Basic Auth header. Do not manually remove the credentials unless your SimpleFIN provider has given you another authentication method.

No Account Map Matches

Run setup_suggest_account_map again and compare the draft with account-map.json. If Firefly III account names changed, update firefly_account_id and firefly_name.

Empty Missing Transaction Results

An empty result can mean Firefly III is up to date, the date range is too narrow, or the account map points at the wrong Firefly account. Try a wider range and verify the mapping with the setup tools.

Security Model

This server is designed to be read-only for financial systems.
No Firefly III write endpoints are implemented.
No SimpleFIN mutation endpoints exist in this project.
reconcile_run_audit writes local audit-history JSON only.
reconcile_prepare_review_plan reads local audit history only and does not mutate financial systems.
Category rule tools write local category-rules JSON only.
Ignored-finding tools write local ignored-findings JSON only.
setup_save_account_map only writes local config after explicit confirmation.
Secrets are read from environment variables and are not logged intentionally.
Returned account and transaction identifiers are masked where possible.

Available Tools

19 tools

firefly_find_possible_duplicatesFind Firefly DuplicatesA

Read-onlyIdempotent

Find possible duplicate Firefly III transactions using same mapped account, amount, nearby date, and description similarity.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No
`account`	No
`end_date`	No
`start_date`	No

TDQS

A3.5/5.0

Behavior5/5

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

The description goes beyond annotations by detailing the matching logic (account, amount, date, description similarity). Annotations indicate read-only, idempotent, non-destructive behavior, which aligns with 'find' semantics. No contradiction.

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

Conciseness5/5

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

The description is a single sentence with no unnecessary 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.

Completeness2/5

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

Despite having four parameters and no output schema, the description fails to explain parameter usage or return format. The tool has no required parameters, but the description doesn't clarify defaults or behavior with no arguments. This leaves significant gaps for an agent.

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

Parameters1/5

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

Schema description coverage is 0%, so the description must explain parameters. It mentions 'amount' but no `amount` parameter exists. It does not clarify how `days`, `start_date`, `end_date`, or `account` relate to the matching criteria. This omission and misrepresentation makes the parameters poorly communicated.

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

Purpose5/5

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

The description clearly states the tool finds possible duplicate Firefly III transactions and specifies the matching criteria: same mapped account, amount, nearby date, and description similarity. This distinguishes it from sibling tools like setup or reconciliation tools.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it or which sibling tools might be more appropriate for related tasks.

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

firefly_summarize_uncategorizedSummarize Uncategorized Firefly TransactionsA

Read-onlyIdempotent

Group Firefly III transactions with missing categories by likely merchant and suggest category labels without applying them.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No
`account`	No
`end_date`	No
`start_date`	No

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare readOnlyHint true, destructiveHint false, etc. The description reinforces non-destructive behavior ('suggest without applying'), but adds limited new context beyond annotations. No side effects or additional behavioral details are disclosed.

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

Conciseness5/5

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

The description is a single, concise sentence that front-loads the core action and key nuance (without applying). No unnecessary words or repetition of schema fields.

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

Completeness2/5

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

Despite being a read-only analysis tool, the description omits expected outputs, grouping criteria, and parameter roles. With no output schema and zero param coverage, the agent lacks sufficient context to use the tool effectively.

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

Parameters1/5

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

Schema description coverage is 0%, and the description fails to explain any of the four parameters (days, account, end_date, start_date). The agent has no guidance on how parameters affect grouping or which are needed, severely hampering correct invocation.

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

Purpose5/5

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

The description clearly states the tool's function: grouping transactions with missing categories by likely merchant and suggesting category labels without applying them. This is a specific verb+resource combination that distinguishes it from sibling tools (setup, reconcile, etc.).

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

Usage Guidelines4/5

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

The description implicitly indicates read-only use ('without applying them'), aligning with annotations. However, no explicit guidance on when to use this tool versus alternatives is provided, though siblings are sufficiently different to infer context.

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

reconcile_check_balance_mismatchesCheck Balance MismatchesC

Read-onlyIdempotent

Compare mapped SimpleFIN account balances against Firefly III account balances.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No
`account`	No
`end_date`	No
`tolerance`	No
`start_date`	No

TDQS

C2.6/5.0

Behavior2/5

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds no behavioral details beyond the basic comparison, such as output format or side effects.

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

Conciseness3/5

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

The description is a single sentence, which is concise, but it lacks necessary detail about parameters and behavior, making it under-specified. It is not optimally sized for completeness.

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

Completeness1/5

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

With 5 unspecified parameters, no output schema, and no clarification of 'mapped', the description leaves significant gaps. For a comparison tool, details on tolerance, date ranges, and return values are critical.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not explain any of the 5 parameters (days, account, end_date, tolerance, start_date). The description fails to compensate for the missing parameter documentation.

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

Purpose5/5

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

The description clearly states the action ('compare') and the specific resources ('mapped SimpleFIN account balances against Firefly III account balances'), distinguishing it from siblings like 'reconcile_find_missing_transactions' that deal with transactions.

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

Usage Guidelines2/5

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 vs. alternatives such as 'reconcile_find_missing_transactions' or 'reconcile_run_audit'. The purpose is clear, but context for selection is missing.

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

reconcile_check_stale_accountsCheck Stale AccountsA

Read-onlyIdempotent

Compare latest SimpleFIN transaction dates against latest Firefly III transaction dates for mapped accounts.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No
`account`	No
`end_date`	No
`start_date`	No

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds the context of date comparison but does not detail behavior such as what happens if accounts have no transactions or how results are formatted. This is adequate but not enhanced beyond annotations.

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

Conciseness5/5

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

The description is a single sentence that conveys the core purpose without any filler. It is front-loaded and efficient.

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

Completeness2/5

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

Without an output schema, the description should explain what the tool returns or how it indicates staleness. It also fails to document the parameters. Given the tool's moderate complexity (4 params), more detail is needed for an agent to invoke it correctly.

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

Parameters2/5

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

The input schema has 4 parameters with 0% description coverage. The description does not clarify the meaning or usage of 'days', 'account', 'start_date', or 'end_date'. It only vaguely refers to 'latest transaction dates', leaving the agent to guess parameter roles.

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

Purpose5/5

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

The description clearly states the tool's function: comparing latest SimpleFIN transaction dates against Firefly III dates for mapped accounts. It uses a specific verb ('Compare') and resource ('transaction dates'), which distinguishes it from sibling tools like reconcile_find_missing_transactions or reconcile_check_balance_mismatches.

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

Usage Guidelines3/5

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

The description implies the tool is for identifying stale accounts by comparing dates, but it does not explicitly state when to use it versus alternatives, nor does it provide any exclusions or context about prerequisites.

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

reconcile_find_missing_transactionsFind Missing TransactionsB

Read-onlyIdempotent

Compare mapped SimpleFIN and Firefly III accounts, returning SimpleFIN transactions that appear absent from Firefly III.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No
`account`	No
`end_date`	No
`start_date`	No

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds that it compares mapped accounts and returns missing transactions, but no further behavioral details (e.g., pagination, performance) are provided.

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

Conciseness4/5

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

The description is a single, efficient sentence with no redundancy. However, it lacks any structure (e.g., bullet points) that could improve readability, especially for a tool with multiple parameters.

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

Completeness2/5

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

Given the 0% parameter coverage and absence of an output schema, the description should provide more context about what the tool does with its parameters and what the output looks like. The current description is insufficient for complete understanding.

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

Parameters1/5

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

Schema description coverage is 0% and the description provides no information about the four parameters (days, account, start_date, end_date), leaving the agent without guidance on how to use them effectively.

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

Purpose5/5

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

The description clearly states the verb ('compare... returning') and the resource ('SimpleFIN transactions absent from Firefly III'), and distinguishes it from sibling tools like reconcile_run_audit or check_balance_mismatches by focusing on finding missing transactions.

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

Usage Guidelines3/5

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

The description implies use during reconciliation to find missing transactions, but does not explicitly state when to use it versus alternatives (e.g., reconcile_run_audit) nor when not to use it. No exclusions or prerequisites are mentioned.

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

reconcile_prepare_review_planPrepare Audit Review PlanA

Read-onlyIdempotent

Create a compact manual review plan from the latest local audit history snapshot without mutating Firefly III or SimpleFIN.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.1/5.0

Behavior3/5

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds context about not mutating Firefly III or SimpleFIN and using local snapshot, which is consistent but not extensive beyond annotations.

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

Conciseness5/5

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

Single sentence with no filler, every word adds value. Perfectly concise and front-loaded.

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

Completeness5/5

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

Given zero parameters, no output schema, and rich annotations, the description fully covers the tool's purpose and behavioral constraints without gaps.

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

Parameters4/5

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

No parameters exist, and schema coverage is 100%. The description does not need to explain parameters, so baseline 4 is appropriate.

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

Purpose5/5

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

The description uses a specific verb ('Create') and clearly identifies the resource ('compact manual review plan') and source ('latest local audit history snapshot'). It distinguishes from sibling tools by emphasizing it does not mutate external systems.

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

Usage Guidelines3/5

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

The description implies this tool is used after an audit history snapshot and before manual review, but lacks explicit guidance on when to use vs. alternatives 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.

reconcile_run_auditRun Reconciliation AuditB

Run the full reconciliation audit without mutating financial systems. Saves a compact local audit-history snapshot.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No
`account`	No
`end_date`	No
`start_date`	No
`max_missing`	No
`max_duplicates`	No
`include_details`	No
`include_ignored`	No
`max_uncategorized_groups`	No
`min_duplicate_confidence`	No

TDQS

B3.4/5.0

Behavior4/5

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

The description adds value beyond annotations by specifying that financial systems are not mutated but a local snapshot is saved. This clarifies the false readOnlyHint and non-destructive nature. However, it could elaborate on other behavioral traits like idempotency 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.

Conciseness5/5

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

Two sentences, front-loaded with the primary action, no redundant words. Every sentence adds meaning.

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

Completeness1/5

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

Given 10 parameters with no descriptions and no output schema, the description is severely incomplete. It lacks sufficient context for complex parameter selection and return value understanding.

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

Parameters1/5

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

With 0% schema description coverage and no parameter explanations in the description, the agent has no guidance on what parameters like days, account, or end_date mean. The description does not compensate at all.

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

Purpose5/5

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

The description clearly states the tool's action ('Run the full reconciliation audit') and resource ('audit'). It distinguishes from sibling tools which are for setup, finding, or checking.

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

Usage Guidelines3/5

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

The description implies a safe, read-only audit use case ('without mutating financial systems') but does not explicitly state when to use this tool over alternatives or provide any when-not-to guidance.

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

setup_add_category_ruleAdd Category RuleA

Idempotent

Add or update a local category suggestion rule. This only writes local config and never mutates Firefly III or SimpleFIN.

ParametersJSON Schema

Name	Required	Description	Default
`match`	Yes
`category`	Yes

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already indicate idempotent and non-destructive behavior. The description adds valuable context by clarifying it only modifies local config and never touches Firefly III or SimpleFIN, which goes beyond annotations.

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

Conciseness5/5

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

Description is two sentences with no unnecessary words, effectively conveying purpose and safety scope.

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

Completeness3/5

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

Lacks parameter semantics and does not discuss return values or how the rule interacts with other tools (e.g., listing rules). For a simple tool, this is adequate but with gaps.

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

Parameters2/5

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

Schema description coverage is 0%, and the description does not explain what 'match' and 'category' mean. The agent must infer semantics from parameter names and constraints, which is insufficient.

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

Purpose5/5

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

Description clearly states the action ('Add or update') and the resource ('local category suggestion rule'), and distinguishes it from tools that interact with external systems by clarifying it only writes local config.

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

Usage Guidelines3/5

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

Description implies usage (local config only) but does not explicitly state when to use this tool versus alternatives like setup_remove_category_rule 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.

setup_get_statusGet Setup StatusA

Read-onlyIdempotent

Show finance-reconcile-mcp setup status, including the account-map path and validation state.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.1/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description does not need to repeat safety. The description adds value by specifying the content (account-map path and validation state). However, it does not disclose any additional behavioral traits beyond what annotations and the name imply.

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

Conciseness5/5

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

The description is a single, front-loaded sentence that conveys all necessary information without any extraneous words. It efficiently states the purpose and key details.

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

Completeness5/5

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

Given there are no parameters, no output schema, and rich annotations already present, the description adequately covers what the tool does and what information it returns. It specifies the two key pieces of status information (account-map path and validation state), making it complete for a status check tool.

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

Parameters4/5

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

There are zero parameters, and schema description coverage is 100% by default. The baseline for no parameters is 4, and the description does not need to add parameter information. No further improvement needed.

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

Purpose5/5

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

The description uses a specific verb ('Show') and explicitly names the resource ('finance-reconcile-mcp setup status') with concrete details (account-map path, validation state). This clearly distinguishes it from sibling tools that perform actions (e.g., setup_suggest_account_map) or list other items (e.g., setup_list_simplefin_accounts).

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

Usage Guidelines3/5

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

No explicit guidance on when to use or not use this tool. The description implies it's for checking status, but there is no mention of prerequisites, alternatives, or when to avoid it. The context of sibling tools suggests it's a safe read operation, but the description itself lacks explicit usage guidelines.

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

setup_ignore_findingIgnore FindingA

Idempotent

Add a finding fingerprint to the local ignored-findings file. This never mutates Firefly III or SimpleFIN.

ParametersJSON Schema

Name	Required	Description	Default
`type`	Yes
`reason`	Yes
`fingerprint`	Yes

TDQS

A3.8/5.0

Behavior4/5

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

Annotations indicate idempotency and non-destructiveness. The description adds that it never mutates Firefly III or SimpleFIN, clarifying the scope of side effects. However, it does not explain what happens if the fingerprint already exists (e.g., overwrite or ignore), which would enhance transparency.

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

Conciseness5/5

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

Two sentences, no unnecessary words. The description is front-loaded with the core action and includes a clarifying statement about side effects. Every sentence adds value.

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

Completeness3/5

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

Given the three required parameters and no output schema, the description is adequate but has gaps. It does not explain what a 'finding fingerprint' is, how to obtain one, or the effect of the tool in the broader workflow. However, sibling tools like setup_list_ignored_findings provide context.

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

Parameters2/5

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

Schema coverage is 0%, so the description must compensate. It mentions 'finding fingerprint' but does not explain the 'type' or 'reason' parameters. The enum values for type are somewhat self-explanatory, but the description should clarify the role of each parameter.

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

Purpose5/5

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

The description clearly states the action ('Add') and the resource ('finding fingerprint to the local ignored-findings file'). It distinguishes from sibling tools like setup_unignore_finding by focusing on adding rather than removing.

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

Usage Guidelines3/5

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

The description does not explicitly state when to use this tool versus alternatives. It implies usage for ignoring findings, but lacks explicit guidance on conditions or exclusions. The note about not mutating external systems provides some context but not usage advice.

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

setup_list_category_rulesList Category RulesA

Read-onlyIdempotent

List local category suggestion rules. This only reads local config and never mutates Firefly III or SimpleFIN.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.7/5.0

Behavior5/5

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

Description adds context beyond annotations: it reads only local config and never mutates Firefly III or SimpleFIN. This aligns with readOnlyHint and reinforces the safe, nondestructive behavior.

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

Conciseness5/5

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

Single sentence that is front-loaded with the tool's primary action. No wasted words.

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

Completeness5/5

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

For a zero-parameter, no-output-schema tool, the description provides enough context: what it does (list), what it affects (local config only), and that it is read-only. No gaps.

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

Parameters4/5

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

No parameters exist, so schema coverage is complete. Description does not need to add param info; it's sufficient that it states the function without requiring parameters.

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

Purpose5/5

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

Description clearly states the tool lists local category suggestion rules. Verb and resource are specific, and the read-only nature is explicitly mentioned, distinguishing it from mutation tools like setup_add_category_rule.

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

Usage Guidelines4/5

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

Description implies usage for listing rules without mutation, but does not explicitly contrast with sibling tools that add or remove rules. However, the context of sibling names makes the distinction clear.

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

setup_list_firefly_accountsList Firefly AccountsB

Read-onlyIdempotent

List Firefly III asset/liability accounts for building account-map.json.

ParametersJSON Schema

Name	Required	Description	Default
`type`	No

TDQS

B3.3/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety aspects. It adds context about the use case but does not disclose other behavioral traits like pagination or output format.

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

Conciseness5/5

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

The description is a single, concise sentence with no unnecessary words. It is front-loaded and efficiently communicates the tool's purpose.

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

Completeness2/5

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

Despite annotations covering safety, the description lacks crucial details: the meaning and allowed values of the type parameter, and the output format. For a tool with one undocumented parameter and no output schema, this is insufficient.

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

Parameters1/5

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

The schema has one parameter (type) with 0% description coverage and no enum values. The description does not mention the parameter or its allowed values, leaving the agent without guidance on how to use it.

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

Purpose5/5

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

The description clearly states the tool lists Firefly III asset/liability accounts for building account-map.json. It uses a specific verb (list) and resource (accounts) and distinguishes from sibling tools like setup_list_simplefin_accounts.

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

Usage Guidelines3/5

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

The description mentions the purpose ('for building account-map.json'), implying when to use it, but does not provide explicit guidance on when not to use or how it compares to alternatives like setup_list_simplefin_accounts.

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

setup_list_ignored_findingsList Ignored FindingsA

Read-onlyIdempotent

List locally ignored audit finding fingerprints. This only reads local config and never mutates Firefly III or SimpleFIN.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds context that it only reads local config and never mutates Firefly III or SimpleFIN, which aligns with and reinforces the annotations. No contradictions. It provides additional behavioral insight beyond what annotations offer.

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

Conciseness5/5

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

The description is two concise sentences. The first states the primary action, and the second clarifies its read-only nature. Every sentence earns its place with no redundant or verbose phrasing.

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

Completeness5/5

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

Given zero parameters, no output schema, and thorough annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint), the description is fully complete. It tells the agent what the tool does and its side effects (none on external systems). No additional details are needed.

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

Parameters4/5

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

Schema has zero parameters, so semantic coverage is 100%. The description adds no parameter info, which is appropriate since there are none. Baseline is 4 for a parameterless tool.

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

Purpose5/5

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

The description clearly states the tool lists locally ignored audit finding fingerprints. It distinguishes from sibling tools like setup_ignore_finding and setup_unignore_finding, which mutate state, by specifying it only reads. The verb 'list' and resource 'ignored audit finding fingerprints' are specific and unambiguous.

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

Usage Guidelines4/5

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

The description implies it's safe to call anytime because it only reads local config and never mutates external systems. While it doesn't explicitly state when to use vs alternatives, the context from siblings suggests it's useful before mutating ignored findings. Could be improved by mentioning it's a precursor to ignore/unignore operations.

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

setup_list_simplefin_accountsList SimpleFIN AccountsA

Read-onlyIdempotent

List SimpleFIN accounts for building account-map.json. Returns balances only, no transactions.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior4/5

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds specific return content (balances only, no transactions), which is valuable beyond annotations.

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

Conciseness5/5

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

Two sentences, no waste. Front-loaded with action and purpose.

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

Completeness5/5

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

Complete for a parameterless list tool with rich annotations. Specifies return data clearly. No output schema needed.

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

Parameters4/5

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

No parameters, so baseline 4 applies. Description adds no parameter info, which is acceptable as schema coverage is 100%.

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

Purpose5/5

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

Clearly states action (list), resource (SimpleFIN accounts), and purpose (building account-map.json). Differentiates from sibling tool `setup_list_firefly_accounts` by resource type.

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

Usage Guidelines3/5

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

Implied usage for setup phase through purpose, but no explicit when-to-use or alternatives. Sibling tools like `setup_validate_account_map` suggest a sequence, but the description doesn't guide selection.

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

setup_remove_category_ruleRemove Category RuleA

Idempotent

Remove a local category suggestion rule. This only writes local config and never mutates Firefly III or SimpleFIN.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

Annotations provide idempotentHint=true and destructiveHint=false; the description adds valuable context that it only affects local config and has no external side effects, going beyond the structured metadata.

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

Conciseness5/5

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

Two sentences, each earning its place: purpose first, then behavioral scope. No waste, front-loaded.

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

Completeness4/5

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

For a one-parameter tool with no output schema, it covers purpose and safety scope, but could mention what happens on missing id or success indication.

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

Parameters2/5

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

With 0% schema description coverage, the description does not explain the single 'id' parameter beyond what the schema provides, missing an opportunity to clarify it's the rule identifier.

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

Purpose5/5

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

The description clearly states the verb 'Remove' and the resource 'local category suggestion rule', distinguishing it from siblings like setup_add_category_rule.

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

Usage Guidelines4/5

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

The description explains that it only writes local config and never mutates external systems, providing clear context for safe local use, but lacks explicit when-not-to-use or alternatives.

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

setup_save_account_mapSave Account MapA

Idempotent

Write account-map.json to the configured local account mapping path. This only writes local config and never mutates Firefly III or SimpleFIN.

ParametersJSON Schema

Name	Required	Description	Default
`overwrite`	No
`account_map`	No
`confirm_write`	Yes

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds value by confirming the write is local-only and does not affect external systems, providing useful context beyond the annotations.

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

Conciseness5/5

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

The description is two sentences long, front-loaded with the action, and every sentence contributes meaning without redundancy.

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

Completeness2/5

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

Despite reasonable annotations, the description fails to explain the parameters or what the tool expects as input. For a tool with 3 parameters including a required confirm_write and an undefined account_map, this is a significant gap that leaves the agent underinformed.

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

Parameters1/5

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

Schema description coverage is 0%, and the description provides no information about the three parameters (overwrite, account_map, confirm_write). The agent cannot determine their purpose or required format, especially for the undefined account_map object.

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

Purpose5/5

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

The description clearly states the tool writes account-map.json to a local path, with a specific verb and resource. This distinguishes it from sibling tools like setup_suggest_account_map and setup_validate_account_map, which perform different actions.

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

Usage Guidelines4/5

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

The description explains that the tool only writes local config and never mutates Firefly III or SimpleFIN, providing clear boundary context. While it doesn't explicitly state when not to use it, the exclusion clarifies its limited scope.

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

setup_suggest_account_mapSuggest Account MapA

Read-onlyIdempotent

Fetch SimpleFIN and Firefly III accounts and return a suggested account-map.json draft. Does not write files.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already indicate idempotent and read-only behavior; description adds that it fetches accounts and returns a draft, reinforcing the non-destructive nature. No contradictions.

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

Conciseness5/5

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

Two brief sentences, front-loaded with the main action, and immediately clarifies it does not write files. No unnecessary words.

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

Completeness3/5

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

Adequate for a simple tool with no input and clear action, but lacks details about the output format or how the draft is structured. Could benefit from mentioning it uses stored configs.

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

Parameters3/5

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

Schema coverage is 100% (no parameters), so baseline is 3. Description adds no parameter information since none exist, but could have explained why no input is needed.

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

Purpose5/5

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

Description clearly states it fetches accounts from two specific sources (SimpleFIN and Firefly III) and returns a draft map. Distinguishes from siblings like setup_validate_account_map and setup_save_account_map which have different verbs.

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

Usage Guidelines3/5

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

The description says 'Does not write files' which implies read-only usage, but does not explicitly state when to use this tool over alternatives like setup_validate_account_map or setup_save_account_map. Context from sibling tool names suggests a sequence, but not stated.

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

setup_unignore_findingUnignore FindingA

Idempotent

Remove a finding fingerprint from the local ignored-findings file. This never mutates Firefly III or SimpleFIN.

ParametersJSON Schema

Name	Required	Description	Default
`fingerprint`	Yes

TDQS

A3.9/5.0

Behavior4/5

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description clarifies that the operation only affects a local file and does not mutate external systems. This adds useful behavioral context without contradicting the structured metadata.

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

Conciseness5/5

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

The description is exceptionally concise: two sentences, no extraneous information. The core action is front-loaded in the first sentence, making it immediately clear.

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

Completeness4/5

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

For a simple tool with one parameter and no output schema, the description covers the essential aspects: the action and its scope (local only). It is complete enough given the complexity, though a brief note on what a fingerprint is would raise it further.

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

Parameters2/5

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

The schema has 0% description coverage for the single parameter 'fingerprint', and the tool description does not explain what a fingerprint is or its expected format. The minimal context 'Remove a finding fingerprint' implies it identifies a finding, but this is insufficient for precise usage.

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

Purpose5/5

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

The description clearly states the action: 'Remove a finding fingerprint from the local ignored-findings file.' The verb 'remove' and resource 'finding fingerprint' are specific. It implicitly distinguishes from the sibling 'setup_ignore_finding' which would add rather than remove, though not explicitly named.

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

Usage Guidelines3/5

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

The description provides limited guidance on when to use this tool. It states that it 'never mutates Firefly III or SimpleFIN,' which is helpful context but does not explicitly contrast with siblings or specify prerequisites or scenarios where this tool is preferred over alternatives.

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

setup_validate_account_mapValidate Account MapB

Read-onlyIdempotent

Validate an account-map JSON object or the configured account-map.json file, optionally checking live SimpleFIN and Firefly accounts.

ParametersJSON Schema

Name	Required	Description	Default
`account_map`	No
`check_remote`	No

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it can optionally check live accounts via check_remote. However, it does not explain what validation entails (e.g., structural checks, account existence, connectivity) or what happens on failure. With annotations covering safety, a score of 3 is appropriate because the description adds some value 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.

Conciseness5/5

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

The description is a single sentence that is front-loaded with the core action ('Validate an account-map JSON object or the configured account-map.json file'). No unnecessary words; every part contributes to understanding the tool's scope.

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

Completeness2/5

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 should clarify what the validation result looks like (e.g., errors, success message). It also does not mention validation criteria (e.g., required fields, account existence checks). Given the complexity of validating an account map against live accounts, this omission leaves the agent needing to infer behavior.

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

Parameters3/5

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

Schema coverage is 0%, so the description must compensate. The description explains check_remote ('optionally checking live SimpleFIN and Firefly accounts') but only vaguely hints at account_map ('account-map JSON object'). The type and expected structure of account_map are not clarified. This partially compensates for the lack of schema descriptions but is not thorough enough for a high score.

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

Purpose4/5

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

The description clearly states the tool validates an account-map JSON object or file, and optionally checks live SimpleFIN and Firefly accounts. It distinguishes from sibling tools like setup_suggest_account_map (which suggests mappings) and setup_save_account_map (which saves). However, it does not explicitly differentiate among other validate-type tools, and the specific meaning of 'validate' is somewhat vague.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as needing a configured account map first, or that this should be used before saving. Sibling tools like setup_save_account_map suggest a workflow, but no comparison is given.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

19 tool updatesv0.3.0Jul 29, 2026
- First observedfirefly_find_possible_duplicates
- First observedfirefly_summarize_uncategorized
- First observedreconcile_check_balance_mismatches
- First observedreconcile_check_stale_accounts
- First observedreconcile_find_missing_transactions
- First observedreconcile_prepare_review_plan
- First observedreconcile_run_audit
- First observedsetup_add_category_rule
- First observedsetup_get_status
- First observedsetup_ignore_finding
- First observedsetup_list_category_rules
- First observedsetup_list_firefly_accounts
- First observedsetup_list_ignored_findings
- First observedsetup_list_simplefin_accounts
- First observedsetup_remove_category_rule
- First observedsetup_save_account_map
- First observedsetup_suggest_account_map
- First observedsetup_unignore_finding
- First observedsetup_validate_account_map

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored 2026-07-29 21:20 across 19 tools

Disambiguation5/5

All tools have clearly distinct purposes, with prefixes (setup_, reconcile_, firefly_) grouping them by domain. Even within the large setup group, each tool targets a unique action or object, leaving no ambiguity.

Naming Consistency5/5

Tool names follow a consistent pattern: {domain}_{action}_{object} using snake_case. The prefixes are uniform, and verbs and nouns are used predictably throughout the set.

Tool Count4/5

19 tools is slightly above the ideal range of 3-15 but still well-scoped for the domain. Each tool contributes to setup, reconciliation, or Firefly-specific operations without unnecessary redundancy.

Completeness4/5

The tool set covers the full reconciliation lifecycle: setup (mapping, rules, ignored findings), reconciliation audit (missing transactions, stale accounts, balance mismatches), and Firefly analysis (duplicates, uncategorized). Minor gaps like automated transaction creation are likely intentional to avoid mutation.

Maintenance

ActivityInactive

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

thoughtsOAuth
ai.thoughtbox.api
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Cloud Storage Finance
2
The Quiet Protocol Growth Offense MCP A
com.thequietprotocol.www
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Databases Research & Data Finance
292
turva-mcp A
dev.turva
Read-only MCP server for turva.dev, an agent-readiness audit and advisory service.
Autonomous Agents Developer Tools Security
52
modern-treasury A
io.usefulapi
MCP server for Modern Treasury — payment orders, transactions, counterparties and ledgers.
Finance Payments & Billing
172

Related MCP Servers

ynab-mcp-bridge
Finance
mossipcams
A
license
Not graded
quality
C
maintenance
Read-only MCP server for YNAB that provides tools for budgets, accounts, categories, transactions, and financial summaries via HTTP or stdio.
Updated 2 months ago (2026-07-02 19:33 UTC)
1
MIT
Ogarni.AI MCP Server
Finance
IsidoreSoftware
F
license
A
quality
C
maintenance
Read-only MCP server for accessing personal finance data from Ogarni.AI, including receipts, categories, summaries, notifications, and more.
Updated a month ago (2026-08-10 15:03 UTC)
20
-
FinTS-Finanzen
Finance Security
NG-Bullseye
A
license
Not graded
quality
C
maintenance
Read-only MCP server for FinTS/HBCI banking; enables account information retrieval such as balances and transactions via PIN-TAN.
Updated a month ago (2026-08-05 12:54 UTC)
MIT
@jbctechsolutions/mcp-mercury
Finance
jbctechsolutions
A
license
A
quality
C
maintenance
Read-only MCP server for Mercury business banking — accounts, transactions, and statements.
Updated 2 months ago (2026-07-07 05:26 UTC)
6
16
MIT