A
licenseNot graded
qualityD
maintenanceEnables AI agents to manage personal expenses through natural language conversations. Supports adding, searching, and analyzing transactions with automatic categorization and financial insights.
3
MIT
financial-agent
by albeorla
The financial-agent server is a local MCP server for managing personal finances with a deterministic, evidence-backed pipeline — every number traced to a source row, never invented. Key capabilities include:
Data Ingestion: Sync accounts, balances, and transactions from SimpleFIN; record manual balance snapshots; import card statements (e.g. Apple Card CSV); and pull Todoist tasks into the local DB.
Financial Status & Cash-Flow Modeling: Generate deterministic day-by-day cash-flow projections, human-readable daily digests (working cash, upcoming obligations, drift, guardrail status), and spending summaries by category, merchant, or month.
Obligations & Income: Create, update, and list obligations and their dated instances; manage income sources and schedules; generate dated income instances; and import calendar/pay-date facts.
Recurring Charge Onboarding: Scan transaction history for recurring charge patterns, work a prioritized review queue, record decisions, preview and apply candidates as canonical obligations, and auto-apply high-confidence charges.
Statement Cycle Management: Aggregate card charges into statement cycles, recompute estimates from card-input rollups (never overwrites confirmed amounts).
Reconciliation & Drift Detection: Match expected obligation instances to observed transactions, confirm/reverse matches (never auto-pays), detect missing payments, stale estimates, amount changes, and unmodeled charges.
Guardrails: Evaluate operating rules (cash floor, drift threshold, debt avalanche order) with severity-ordered findings.
Goals & Follow-ups: Track savings targets with pace tracking; manage dated reminders; surface a prioritized queue of everything needing attention today.
Todoist Integration: Idempotently push due items to Todoist via an emissions ledger, reconcile task completions back into the model, import Todoist tasks as one-off obligations, and manage individual tasks (write-gated).
Verification: Run deterministic SQL/Python identity checks (projection identity, duplicate instances, statement identity, sign sanity) and optionally spawn an independent adversarial AI reviewer to flag risky forecast areas.
Memory: Store and retrieve corrections, decisions, and facts using bag-of-words similarity search.
Background Automation: Orchestrate the full pipeline (sync → scan → reconcile → drift → verify → surface) as one auditable run with a step-by-step event log; inspect job health and run history.
Migration & Validation: Seed a fresh DB from legacy files, validate the pipeline on a throwaway copy of live data, and diff new digests against legacy cash-flow reports for parity.
Allows managing finance review tasks via Todoist, including reading tasks, converting them to obligations, and writing review batches as Todoist tasks (with dry-run by default).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@financial-agentwhat's my projected cash flow for the next month?"
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.
personal-finance-agent
A local Model Context Protocol (MCP) server that gives an AI agent grounded, evidence-backed tools for managing personal finances.
It is deterministic and it never invents numbers. Every balance, due date, projection endpoint, and cash-flow figure the agent reports is backed by a tool result computed over a local SQLite database — not estimated, not recalled from a prior message. A built-in grounding check (verify_grounding) exists specifically to confirm that each headline dollar figure traces back to a source row before the agent is allowed to state it.
The server runs entirely on your machine, talks to your own data sources (a bank-aggregation feed and a task manager), and exposes that data to an MCP client (such as Claude Code) as a catalog of finance tools.
Architecture at a glance
flowchart LR
Claude["Claude / MCP client"] <-->|"tool calls"| Server["Finance MCP Server<br/>90 tools"]
SimpleFIN["SimpleFIN<br/>balances + transactions"] -->|"sync_simplefin"| Server
Portals["Bank/card portals<br/>manual balance inputs"] -->|"set_manual_balance"| Server
Server <-->|"read/write source rows"| SQLite[("SQLite finance DB<br/>balances, transactions, obligations, instances")]
Server <-->|"decisions, corrections, facts"| Memory[("finance_memory")]
Server -->|"surface_due_items_to_todoist<br/>deduped by emissions ledger"| Todoist["Todoist Finance project"]
Todoist -->|"completion read-back"| Server
classDef client fill:#e7eff7,stroke:#1f4e79,color:#17202a
classDef server fill:#e8f2ec,stroke:#3d7b65,color:#17202a
classDef source fill:#f5ecdd,stroke:#b87922,color:#17202a
classDef output fill:#f4e6ea,stroke:#aa4a5d,color:#17202a
classDef store fill:#edf0f2,stroke:#2f3b47,color:#17202a
class Claude client
class Server server
class SimpleFIN,Portals source
class Todoist output
class SQLite,Memory storeflowchart LR
subgraph Ingest["1. INGEST"]
Sync["sync_simplefin<br/>pull balances + transactions"]
Manual["set_manual_balance<br/>correct stale balance-only feeds"]
CardPaste["import_card_statement<br/>paste a card statement (dry-run by default)"]
ReadBack["reconcile_todoist_completions<br/>absorb task completions"]
end
subgraph Model["2. MODEL"]
Candidates["scan_charge_onboarding_candidates<br/>discover recurring charges"]
Reconcile["reconcile_obligation_instances<br/>match expected to observed"]
Projection["get_finance_status / get_daily_digest<br/>project cash flow from obligation_instances"]
Guardrails["evaluate_guardrails<br/>cash floor, drift, debt order"]
end
subgraph Surface["3. SURFACE"]
Queue["get_surface_queue<br/>prioritize what needs attention"]
Digest["get_daily_digest<br/>status, working cash, upcoming obligations"]
TodoistPush["surface_due_items_to_todoist<br/>write-gated, deduped output"]
end
Ingest --> Model --> Surface
Surface -. "next daily run" .-> IngestThe post-facto design record lives in docs/design-doc.md, and more durable Mermaid diagrams live in docs/diagrams.md.
Related MCP server: Finance MCP Server
What it does: INGEST -> MODEL -> SURFACE
The server implements a single loop. Each stage is deterministic and idempotent, and none of it mutates the original source database.
1. INGEST — pull the facts in
SimpleFIN sync (
sync_simplefin) pulls live accounts, balances, and transactions into the local DB via idempotent upsert (default 90-day window;incrementalmode resumes from the last synced transactions so a daily run stays cheap). Read-only against SimpleFIN.Manual balance snapshots (
set_manual_balance) handle balance-only feeds that refresh slowly — for example a card whose portal shows "Updated Monthly". A manual snapshot is written as an ordinarybalance_snapshotsrow (source='manual') and is treated as authoritative for its calendar day, so the agent reads current reality instead of a stale feed value.Card-statement paste (
import_card_statement) fills the balance-only blind spot for cards with no live transaction feed (for example the Apple Card). Paste a monthly CSV or statement export: it parses into real transaction rows (source='apple_card_paste'), dedups against prior pastes via a deterministic synthetic id, fuzzy-matches the account, and feeds both the onboarding scanner and the statement-estimate rollup. When the paste carries a statement total, the card's statement instance is promoted to that observed amount and a sticky manual balance is recorded. Defaults todry_run=True(parse + preview only); re-run withdry_run=falseto write.
2. MODEL — turn facts into a forecast
Obligations and dated instances are the cash-flow truth. A durable obligation plus its exact dated
obligation_instancesdrive a deterministic, day-by-day cash-flow projection over the requested windows. The projection reads only obligation instances — nothing else can move the forecast.Recurring-charge onboarding discovers candidate recurring charges from transaction history and stages them in a review queue. Candidates are not cash-flow truth: they never write obligation instances and cannot change the forecast until a human accepts and applies them. A candidate classifier triages each discovery into
surface(worth a human look),park(low-signal, held quietly), orauto_reject(clear noise), with safety backstops so anything large, recurring with high confidence, or otherwise material is never silently rejected and always gets surfaced.Reconciliation and drift match expected instances against observed transactions, and flag missing payments, stale estimates, amount changes, and unmodeled recurring charges. Estimates contradicted by a live balance (for example an averaged charge still projecting against a dormant, paid-off card) are auto-expired so stale outflows stop skewing the forecast.
Goals track savings targets and pace; follow-ups are dated reminders the daily routine fires on.
Guardrails carry forward operating rules of thumb as explicit, evidence-backed checks (for example a cash floor: the projected lowest balance must not drop below a threshold).
3. SURFACE — push what needs attention
A daily routine collects everything worth acting on today (matches to confirm, goals behind pace, estimates past review, stale balance-only snapshots, guardrail trips) into one prioritized queue (
get_surface_queue/get_daily_digest).surface_due_items_to_todoistpushes those items to Todoist through an idempotent emissions ledger. Each action-queue item names either its direct task or its membership in thefinance-statusrollup. A bill whose due date moved is re-keyed onto its existing open task rather than getting a second one, so the board never carries the same question twice. Completing a snapshot task acknowledges only that task's evidence hash, so changed evidence resurfaces. A truefollowup:<id>completion still resolves its source follow-up.The surfaced daily run finishes with a conservation check against a fully paginated Todoist read. Every current action must have an open managed task, a dismissal for the current evidence hash, or documented membership in the live
finance-statusrollup. Missing coverage and partial Todoist reads make the run non-green.
Tool catalog
The server registers 90 MCP tools. They group by area as follows. (Names are exact; see src/financial_agent/server.py for signatures.)
Ingest
sync_simplefin: pull accounts, balances, and transactions from SimpleFIN by idempotent upsert (read-only against the feed). A feed row that lands after a checking paste absorbs the pasted copy (same account, posted date, and amount), re-pointing any matches or evidence at the feed row.set_manual_balance: record an authoritative-for-the-day balance snapshot for a slow-refreshing, balance-only feed.import_checking_activity: paste checking-account activity as CSV for the manual-sourced operating account. Parses date/description/amount rows, fuzzy-matches the account, stamps deterministic synthetic ids so a re-paste is idempotent, skips rows the SimpleFIN feed already has (reported asfeed_duplicate; the feed row wins), and writes real transaction rows (source='checking_paste'). Passbalanceto record a sticky manual balance in the same write. Dry-run by default.dedupe_pasted_transactions: one-time cleanup for history imported before the feed-duplicate skip. Pairs eachchecking_pasterow with a feed row on the same account, posted date, and amount, re-points reconciliation matches and evidence at the feed row, and deletes the paste copy. Dry-run by default; reports the pairs and the double-counted total.import_card_statement: the card-statement equivalent (see Statement cycles, below).
Status, projection, and digest
get_finance_status— compact by default: balances, source freshness, projection summaries, guardrail findings,trace_id, and result references. Passcompact=falsefor full per-day event arrays.get_daily_digest— the human-readable morning summary (working cash, multi-window projection, upcoming obligations with running balances, drift/review items, recurring candidates, and a GREEN/YELLOW/RED status), each with provenance. Also includes an obligation coverage summary (how much of what you owe is modeled vs silent autopay vs unmodeled discovered charges) and a trough-sensitivity line that shows how much the projected low point swings on its estimated outflows, so a precise-looking low point is not read as fact. Also carries a read-onlyverificationblock (ok flag plus per-severity finding counts and details) from the deterministic verification phase, so a digest that reads clean while its source rows disagree shows up immediately. When the adversarial reviewer has run, it also carries anadversarial_reviewblock: the persisted advisory flags from an independent reviewer, clearly labeled attention-routing (look here, this looks off), never a verdict. The digest only reads these persisted rows; it never spawns the reviewer.summarize_spending— outflow spending by category / merchant / month with totals, a month-over-month trend, and the transaction ids behind each bucket (rules-based, no LLM).list_transactions: individual transactions, newest first, so an exact charge amount can be quoted instead of only the aggregates fromsummarize_spending. Filters: date range, substring query over payee and description, minimum absolute amount, account, pending. Limit caps at 500 and atruncatedflag signals more rows matched.verify_grounding— the "is the agent allowed to say this number" gate: confirms each headline figure traces to a source row.
Obligations and instances
apply_obligation_instances,delete_obligation_instance,list_obligationsset_obligation_end: set or clear the date a recurring bill stops projecting (a lease, a loan payoff, a subscription being cancelled), so it does not fill the runway forever. Reversible: instances are excluded past the end date, not deleted.deactivate_obligation: retire a whole obligation so all its instances drop out of the projection, listings, reconciliation, and drift. Rows are preserved for audit and it reports how many upcoming bills it pulled from the runway.list_obligation_review_candidates— estimated amounts whose review date has arrived (for example a statement estimate to refresh after close).list_statement_input_estimates— card-spend estimates that feed statement estimates without directly reducing checking cash flow.
Income and calendar
list_income_sources,apply_income_source,generate_income_instancesimport_calendar_facts,list_calendar_facts— normalized pay-date and business-closure facts that drive income scheduling.
Recurring-charge onboarding (discover -> review -> apply)
scan_charge_onboarding_candidates— deterministic background discovery; proposes candidates, never writes canonical obligations.list_charge_onboarding_queue,get_next_charge_onboarding_candidate— work the queue, prioritized by estimated monthly cash impact.record_charge_onboarding_decision—defer/reject/needs_more_evidence/in_review/accept/reset.record_charge_onboarding_decisions: the same decision for many candidates in one call, to clear a large queue without the one-at-a-time grind. Items apply independently inside one transaction, so a bad item is reported as an error instead of aborting the rest.preview_charge_onboarding_apply— read-only preview of what applying would create.apply_charge_onboarding_candidate— guarded write that promotes an accepted candidate into a canonical obligation plus instances (idempotent: re-applying a window updates in place).auto_model_high_confidence_recurring,backfill_recurring_instances
Statement cycles (for card-statement-payment obligations)
aggregate_statement_inputs,list_statement_cycles,recompute_statement_estimates— roll card-input charges into the statement cycle that pays them; never overwrites a confirmed/observed amount.get_statement_status: the latest closed statement plus the open cycle's pace for one card: spend so far, modeled amount, variance, and whether spend is running ahead of or behind the model.set_statement_actual: record an observed statement balance directly (for example a portal-read Apple Card balance) on the matching statement instance, picked by cycle close date or due date. Written as confirmed with provenance, and never overwritten by the rollup estimator.import_card_statement— paste a monthly card statement (CSV or statement text) for a card with no live transaction feed (for example the Apple Card) to fill the balance-only blind spot. Parses into real transaction rows, dedups against prior pastes, fuzzy-matches the account, feeds the onboarding scanner and statement rollup, and (when a total is supplied) promotes the statement instance to that observed amount. Dry-run by default; re-run withdry_run=falseto write.
Reconciliation and drift
reconcile_obligation_instances— match expected instances to observed transactions (conservative by default; never silently marks paid).list_matched_obligation_instances,list_unmatched_obligation_instanceslist_reconciliation_review_items,confirm_reconciliation_match,unconfirm_reconciliation_match— confirming a match marks an instance paid using its recorded transaction match (guarded — never auto-pays).list_check_suggestions,confirm_check_suggestion,reject_check_suggestion: advisory pairings between a posted generic check and the bill it probably paid. Confirming returns the refreshed projection; rejecting is durable and leaves the bill untouched.suppress_contradicted_estimates: lower or retire an averaged estimate that the account's real burn contradicts (for example a card payment still projecting at full size after actual spending on that card collapsed). Compares modeled monthly outflow to observed burn over a lookback window and either rewrites the amount down or routes the obligation to dormant. Both paths are reversible and emit a drift finding.detect_drift,list_drift_findings
Debts
set_debt_terms: create or update a debt's terms (APR, linked account, revolving flag, minimum payment). Re-running with the same id updates in place. Usebalance_source='manual'with an override for debts that have no synced account.list_debts: debts with live balances, modeled monthly interest, autopay and revolving flags, plus total monthly interest across the revolving debts only.
Guardrails
evaluate_guardrails,list_guardrail_findings,apply_guardrail_rules
Goals
set_goal,list_goals,set_goal_override
Follow-ups and the surface queue
capture_followup,list_due_followups,resolve_followupupdate_followup: edit a follow-up in place by id (reschedule, reword, re-prioritize, relink). Re-capturing instead would create a new row, because the capture id is derived from the content.get_surface_queue— the single read for the daily surfacing job.
Todoist output and the action outbox (writes gated OFF by default; Todoist is output-only)
surface_due_items_to_todoist— idempotent push via the emissions ledger. It recordscreate_pendingbefore transport; after an uncertain response it searches for the embedded[fa:<surface_key>]marker and retries only after a complete read proves absence.reconcile_todoist_emission,reconcile_todoist_completions— adopt pre-existing tasks and record the evidence hash acknowledged by a completion. Checkboxes never approve financial reviews; only true follow-ups resolve their source records.reconcile_todoist_project— server-side LIST + classify of the whole Finance project, cleaning drift via a safe three-rule deletion model (ritual/manual tasks are never deleted).list_todoist_project— the read-only counterpart (LIST + classify, no delete path), so the agent's board read goes through the server, never raw HTTP. Each task entry includes itsdue_dateanddescription, so a due-date audit can run through the MCP without touching the raw Todoist API.create_todoist_task,execute_action_outbox,list_action_outbox— create a one-off reminder and process the durable outbox; nothing is sent externally unless write-back is explicitly enabled.update_todoist_task,complete_todoist_task,reopen_todoist_task,delete_todoist_task— edit, close, reopen, or delete an existing task by id for routine board maintenance; gated the same way (no external call unless write-back is enabled).list_today_tasks_all_projects: read-only sweep of tasks due today or overdue across every project, the companion to the Finance-onlylist_todoist_project. It catches finance-relevant tasks filed under Personal or elsewhere, and leaves relevance to the reader rather than hiding them behind a keyword filter.
Verification (deterministic row-tie checks; no LLM)
run_verification— runs the verification phase: four pure-SQL/Python checks that prove the source rows tie together — projection identity (each window's ending balance equals its start plus its signed events), duplicate instances (no two projectable instances share an obligation and due date), statement identity (a cycle's denormalized input_sum/input_count matches its input rows), and instance sign sanity (no projectable instance has a negative stored amount). Persists each finding by default;persist=Falseis read-only.list_verification_findings— read the recorded verification findings (open by default), newest first, optionally filtered bycheck_idor bysource(deterministicfor the pure-code identity checks,adversarialfor the spawned-reviewer's advisory flags).acknowledge_verification_findings: mark known-open findings as seen so later runs report only new ones. Acknowledged findings stay listable and still resolve automatically once the underlying identity is fixed, but stop flipping the verify summary'sok. Without explicit ids it blanket-acknowledges openwarnfindings and deliberately skipserrorseverity.
Adversarial review (non-deterministic; an independent reviewer, advisory only)
run_adversarial_review— spawn the Claude Code CLI (claude -p) as a read-only subprocess on the user's Claude subscription (OAuth; no Anthropic API key) and ask it to try to refute the riskiest part of the forecast: the estimated, low-confidence outflows that land on the projected low point, the large estimated obligations that move the projection, and the freshly-classified recurring-charge candidates with their evidence. Each flag persists intoverification_findingstaggedsource='adversarial'and surfaces alongside the deterministic checks. Findings are ATTENTION-ROUTING ("look here, this looks off"), never verdicts — the reviewer is a language model and can be wrong. Fail-open: a missing CLI, error, timeout, or unparseable reply returnsavailable=Falseand writes nothing, so a broken reviewer never breaks the run. Runs automatically inside the dailyrun_background_synconly when enabled (see Adversarial review enforcement, below); call it directly to review on demand.
Background runner and job health
run_background_sync— orchestrates the whole pipeline (sync -> scan -> reconcile -> detect drift -> suppress dormant estimates -> verify -> surface due items) as one auditable run with an ordered event log; a failing step is recorded and the run continues. Surfaced runs add a final Todoist coverage check after completion reconciliation. Theverifystep persists its findings tagged with the run id. When the adversarial reviewer is enabled, an extraadversarial_reviewstep runs betweenverifyandsurface_due_items; with the gate off the step does not appear and the default sequence is unchanged.get_background_run,list_background_runs,get_job_healthget_version: the version and git commit of the code the server process is actually running. The server is long-running, so code merged to main only takes effect after a restart; these values are captured at startup, which makes a stale live session visible.
Memory (corrections, decisions, facts to recall)
write_finance_memory,search_finance_memory,list_finance_memories,delete_finance_memory— a deterministic, dependency-free bag-of-words embedding with a context-control retrieval policy (similarity threshold, then top-k, then a token budget).
Migration, validation, and parity (one-time bootstrap and cutover)
apply_obligation_migration— seed a fresh DB from legacy files once (not an ongoing input).run_live_validation— prove the pipeline on live data against a throwaway copy without touching the committed snapshot.compare_to_legacy— diff a legacy cash-flow file against the new digest and report differences with a severity each.
Adversarial review: an independent reviewer for the riskiest numbers
The deterministic verification phase proves the model ties out internally — pure code, so a finding is a genuinely broken identity. The adversarial review answers a softer question that code cannot: does the riskiest part of the forecast look wrong to a fresh pair of eyes? It hands an independent reviewer the highest-leverage rows (the estimated, low-confidence outflows sitting on the projected low point; the large estimated obligations that move the forecast; the freshly-classified recurring-charge candidates and their evidence) and asks it to point at whatever looks off.
Honest framing, baked in. An adversarial finding is attention-routing ("look here, this looks off"), never a verdict. The reviewer is a non-deterministic language model: it can be wrong, miss things, or invent concerns. Findings are stored advisory-labeled and a human decides. They never move the projection and never auto-resolve a deterministic check.
Subscription auth, no API key. The real reviewer spawns the Claude Code CLI (claude -p) as a read-only subprocess using your Claude subscription via OAuth. The child environment has ANTHROPIC_API_KEY removed so it can never silently fall back to a metered API key. The subprocess gets no tools and is isolated from this MCP server (so it cannot recurse); every row it judges is embedded inline in the prompt as untrusted text.
Enable it. The phase is off by default and inert offline and in tests. It runs only when both are true: the environment flag FINANCE_AGENT_ADVERSARIAL is truthy (1/true/yes/on) AND the claude binary resolves on PATH. Optional tuning: FINANCE_AGENT_ADVERSARIAL_MODEL (default fable) and FINANCE_AGENT_ADVERSARIAL_TIMEOUT (seconds, default 300).
Three enforcement layers
The same review is reachable three ways, so a material change cannot slip past review regardless of how the work happens:
Daily run (code). When the gate is on,
run_background_syncappends a gatedadversarial_reviewstep betweenverifyandsurface_due_items. This is the scheduled, always-on path.Inside an MCP call (surfaced reads). The
run_adversarial_reviewtool runs the reviewer on demand, andget_daily_digestsurfaces the persisted advisory flags (a pure read — the digest never spawns the reviewer). An agent working in the model can both trigger a review and see prior flags.Outside the MCP call (Claude Code Stop hook). A
Stophook in.claude/settings.jsonrunspython -m financial_agent.adversarial --as-of <today>once when the agent finishes a turn, so no session ends on an un-reviewed material change. It is debounced by nature (one spawn per turn, not per mutation) and short-circuits instantly when the gate is off.PostToolUse-on-mutations is a stricter alternative; Stop-once-per-turn is the cost-sane default.
The module entry point (python -m financial_agent.adversarial --as-of <YYYY-MM-DD> [--db <path>] [--model <model>]) is safe to run with the gate off — it prints adversarial review disabled and exits 0 without spawning anything.
Setup
Prerequisites
uv for dependency and environment management.
Python >= 3.11 (declared in
pyproject.toml).A SimpleFIN access URL for bank balances and transactions (optional; the server runs without it, just with no live ingest).
A Todoist API token if you want task-board sync and surfacing (optional).
Run the server
uv run financial-agent-mcpFINANCE_AGENT_DB_PATH is required — the server repo holds code only and ships no database, so it never reads an in-repo file. Point it at the SQLite DB in your own working directory; the server creates the file (and its parent directory) and the app schema on first use, so a fresh path in a chosen directory bootstraps cleanly. Source tables (accounts, balances, transactions) are created on the first sync_simplefin run.
Register it as an MCP server
Add an entry to your MCP client's config (for Claude Code, the workspace .mcp.json). The server runs over stdio out of this repo via uv, so no install/copy of the code is needed:
{
"mcpServers": {
"financial-agent": {
"command": "uv",
"args": ["run", "--directory", "/path/to/personal-finance-agent", "financial-agent-mcp"],
"env": {
"FINANCE_AGENT_DB_PATH": "/path/to/your/transactions.sqlite",
"FINANCE_AGENT_ENV": "/path/to/your/.env"
}
}
}
}FINANCE_AGENT_DB_PATH(required) points the server at your local SQLite database; it is created with its parent directory if it does not exist.FINANCE_AGENT_ENVpoints at the.envholding your credentials (defaults to~/dev/areas/finances/.env). Setting it lets a registered server read a sandbox.envwithout touching any other workspace.
Credentials (.env)
Credentials are read from the .env file at runtime and are never logged or committed. Create a .env with placeholder values like the block below — fill in your own:
# Bank / balance + transaction feed (SimpleFIN)
SIMPLEFIN_ACCESS_URL=https://USERNAME:PASSWORD@bridge.simplefin.org/simplefin
# Todoist task board (optional)
TODOIST_API_TOKEN=your-todoist-api-token
TODOIST_PROJECT_ID=your-finance-project-id # optional
# Live Todoist write-back is OFF unless this is truthy (1/true/yes/on).
# With it unset, the outbox stays dry-run and makes no external calls.
TODOIST_WRITE_ENABLED=false # optionalThe presence of each credential is surfaced as a safe boolean (has_simplefin, has_todoist) — the secret values themselves are never returned. If TODOIST_PROJECT_ID is unset, the server falls back to a legacy lookup; set it explicitly to drop that fallback.
Running the tests
uv run --extra dev python -m pytestRun pytest as a module (python -m pytest), not the bare pytest console script: the bare script can resolve to a system Python that lacks the mcp dependency and silently skip the MCP-layer wiring tests. Running as a module pins the project venv, so a green run shows 0 skipped.
Privacy
This repository contains no personal financial data. All balances, transactions, obligations, and credentials live in your local SQLite database and your .env file, both of which are gitignored (*.sqlite, *.db, .env, and the data/ directory are all excluded). The server is read-only against the upstream sources and is designed never to mutate the original feed; live ingest pulls into a local copy.
Todoist write-back is OFF by default. Even with credentials present, the action outbox stays dry-run until TODOIST_WRITE_ENABLED is explicitly turned on.
Available Tools
55 toolsaggregate_statement_inputsB
Group card-statement-input charges into the statement cycle that pays them.
Deterministic and idempotent. Builds statement cycles from the target obligation's statement instances (those with a statement close date) and assigns each card input to its cycle, reporting any inputs that fall past the last known statement close as unrolled.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target_obligation_id | Yes | ||
| db_path | No |
TDQS
B3.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description adds detail: deterministic, idempotent, building cycles from statement instances with close dates, assigning inputs, and reporting unrolled inputs. However, it does not clarify whether the tool modifies state or is read-only, which 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, concise and to the point. It front-loads the main action and adds behavioral details. However, it could be more structured by separating behavior from parameter info.
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, 0% parameter coverage, and 2 parameters. The description explains the process but does not cover input semantics or output format. For a tool that likely creates aggregates, more detail on return values and side effects is needed.
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 explanation of the parameters 'target_obligation_id' and 'db_path'. It mentions 'target obligation' but does not explicitly link to the parameter or describe what 'db_path' does. This forces the agent to guess.
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 'Group' and the resource 'card-statement-input charges', and specifies the outcome: grouping into statement cycles. It also notes determinism and idempotency, which distinguishes it from sibling tools that may be non-deterministic or involve side effects.
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 usage for grouping charges into cycles, but does not provide explicit guidance on when to use this tool versus alternatives like 'list_statement_input_estimates' or 'recompute_statement_estimates'. No when-not or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
apply_charge_onboarding_candidateA
Promote an accepted candidate into a canonical obligation plus dated instances.
This is the guarded write that turns a reviewed candidate into cash-flow truth. By default the candidate must already be accepted (record an accept decision first). Writing is idempotent: re-applying the same window updates instances in place instead of duplicating them.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| candidate_id | Yes | ||
| start_date | No | ||
| through_date | No | ||
| horizon_days | No | ||
| obligation_id | No | ||
| require_accepted | No | ||
| db_path | No |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it is a 'guarded write' and idempotent, updating instances in place, but lacks details on permissions, rate limits, error conditions, or side effects beyond what is described.
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?
Three sentences, front-loaded with the primary purpose, each sentence adds essential context (precondition, idempotency) without waste.
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 7 parameters, no output schema, no annotations, and many sibling tools, the description lacks parameter semantics, return value info, and error handling, making it insufficient for reliable agent use.
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 7 parameters, the description provides no explanation of any parameters (e.g., candidate_id, start_date, horizon_days), failing to add meaning beyond the input schema.
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 promotes an accepted candidate into an obligation with dated instances, using specific verbs like 'promote' and 'apply', and distinguishes from siblings like 'preview_charge_onboarding_apply' and 'record_charge_onboarding_decision'.
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?
Explicitly mentions the precondition that the candidate must be accepted first and that the operation is idempotent, providing clear context for usage, though it doesn't explicitly exclude alternatives like preview or record tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
apply_guardrail_rulesC
Idempotently seed the default guardrail rules into the database.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | No |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states idempotency but does not elaborate on what happens if rules already exist (skip, overwrite, or error). No annotations are provided, so the description carries full burden but omits details like database connection handling, error states, or side effects. Agents lack 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. While very concise, it effectively conveys the core purpose and idempotency. It is appropriately sized for the tool's simplicity, though additional detail could improve completeness without harming conciseness.
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 tool has one parameter, no output schema, and no annotations, the description is insufficiently complete. It does not explain the parameter, return behavior, error conditions, or how it fits among related sibling tools like 'evaluate_guardrails' or 'list_guardrail_findings'. Agents may misuse or underutilize it.
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 sole parameter 'db_path' is not mentioned in the description, and the schema has 0% description coverage. The agent gets no meaningful explanation of what db_path represents (e.g., file path, connection string) or its default behavior when null. The description fails to compensate for the schema gap.
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 uses specific verb 'seed' and resource 'default guardrail rules', making clear it initializes rules in the database. It distinguishes from sibling tools like 'evaluate_guardrails' and 'list_guardrail_findings' which handle different operations, though no explicit differentiation is provided.
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 on when to use this tool versus alternatives. The term 'idempotently' implies it is safe to call multiple times, but no prerequisites, context, or exclusions are stated. A better description would mention typical usage scenario (e.g., initial setup or after migration).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
apply_income_sourceC
Create or update an income source and schedule version after user confirmation.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| db_path | No |
TDQS
C2.4/5.0
Behavior2/5
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 of behavioral disclosure. It notes this is a mutation operation (create/update) with a user confirmation step, but lacks details on idempotency, reversibility, required permissions, or side effects. The information is insufficient for an agent to gauge the tool's impact.
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 short sentence, making it concise. However, it lacks structure such as breaking down key aspects (e.g., behavior, parameters, usage). The sentence is not wasteful but could be more informative without adding length.
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 tool has two parameters (one with no internal schema), no output schema, and no annotations, the description is too brief to provide complete context. It omits critical details like what the 'source' object should contain, how the 'db_path' affects behavior, and what the outcome looks like. An agent would struggle to use this tool correctly.
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%, meaning the parameters 'source' (an object with additionalProperties) and 'db_path' (nullable string) are not documented in the schema. The description does not explain these parameters at all, leaving the agent with no understanding of their meaning or format.
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 creates or updates an income source and schedule version after user confirmation. It uses specific verbs ('create', 'update') and a specific resource ('income source', 'schedule version'). However, it does not explicitly differentiate it from sibling tools like 'list_income_sources' or 'generate_income_instances'.
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 explicit guidance on when to use this tool versus alternatives. The phrase 'after user confirmation' implies a prerequisite, but no when-not-to-use or alternative tools are mentioned. This leaves an agent without clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
apply_obligation_instancesC
Create or update an obligation and exact dated instances.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| obligation | Yes | ||
| instances | Yes | ||
| db_path | No |
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states 'create or update' without disclosing side effects, safety, authentication needs, or limitations. Minimal behavioral transparency.
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?
Single sentence, no fluff. However, it is under-specified, missing critical information. Conciseness without completeness reduces value.
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 no output schema, nested objects in parameters, and no behavioral annotations, the description is insufficient. It does not explain return values, object structure, or usage context.
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 has 3 parameters with 0% description coverage. Description adds no parameter details. The meaning of 'obligation' object, 'instances' array, and 'db_path' is completely unexplained.
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?
Description states 'Create or update an obligation and exact dated instances,' which is a specific verb+resource combination. It distinguishes from siblings like apply_obligation_migration by focusing on instances. However, 'apply' is somewhat vague, and 'exact dated instances' is not fully explained.
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 on when to use this tool versus alternatives. Siblings include apply_obligation_migration, generate_income_instances, etc., but the description offers no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
apply_obligation_migrationA
Migrate the complete obligation set from a legacy source into canonical rows.
source is 'obligations_yaml' (trusted, machine-readable) or 'cashflow_md' (stale narrative, imported as needs_review). Instance-level dedup skips anything already modeled; ambiguous rows become needs_review. dry_run (the default) computes the full plan and writes nothing. Reads the legacy file read-only.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| source | No | obligations_yaml | |
| dry_run | No | ||
| options | No | ||
| db_path | No |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses read-only access to legacy files, dry_run behavior, instance-level dedup, and handling of ambiguous rows. It does not mention error handling or side effects on existing data, but covers key 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear opening sentence explaining purpose, followed by bullet-like details on source types, dedup, dry_run, and read-only behavior. Every sentence contributes essential information without redundancy.
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 no output schema, the description does not explain return values or output format, which is a notable gap for a migration tool. It also fails to document two of five parameters. While core behavior is covered, the description is incomplete for full autonomous use.
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%. The description adds meaning for source (two enumerated values) and dry_run (default previews). However, it ignores path format, options, and db_path parameters, leaving them unexplained. It adds partial value but not enough to compensate for low coverage.
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 purpose: 'Migrate the complete obligation set from a legacy source into canonical rows.' It specifies verb (migrate), resource (obligation set), and distinguishes from sibling tools like list_obligations (read-only) and apply_obligation_instances (applying instances).
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 provides clear context on when to use the tool (migrating legacy obligations), explains the two source types and their reliability, and mentions dry_run as a safe preview. However, it does not explicitly exclude alternatives or state 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.
auto_model_high_confidence_recurringA
Apply HIGH-confidence, well-evidenced direct-checking recurring candidates (e.g. a car payment) as proper obligations so they enter the cash-flow projection and the runway becomes accurate. Conservative: only confidence=high direct-checking with >=3 occurrences; everything else stays in the review queue.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | No | ||
| db_path | No |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must explain behavior. Mentions 'Conservative' and criteria, implying safe mutation. Lacks details on side effects, permissions, or exactly how obligations are applied.
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 succinct sentences with front-loaded action and no redundant words. Efficiently conveys the core functionality and constraints.
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?
Lacks parameter documentation and return value description. With only optional parameters and no output schema, the description should compensate but does not address these missing pieces.
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 coverage is 0%, but description provides no information about the two parameters (as_of_date, db_path). Agent cannot infer their purpose or 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 tool applies high-confidence recurring candidates as obligations for cash-flow accuracy, specifying criteria (confidence=high, direct-checking, >=3 occurrences), distinguishing it from sibling tools that handle different types.
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?
Explicitly states when to use (high-confidence candidates with >=3 occurrences) and that everything else stays in review queue. Implies exclusion but does not name specific alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backfill_recurring_instancesA
Materialize past-due instances for active recurring obligations over a trailing window and reconcile them against posted transactions, so the digest can answer "did rent / Amex / Apple clear this cycle?". Past instances do not enter the cash-flow projection (forward-only); no payment is fabricated - matches come from the normal reconciliation matcher.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | ||
| lookback_days | No | ||
| db_path | No |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: it only processes a trailing window, does not enter cash-flow projections, does not fabricate payments, and uses the normal reconciliation matcher. This gives the agent good understanding of side effects and limitations.
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?
Three sentences with no wasted words. The first sentence immediately states the core purpose, followed by clarifying constraints (forward-only, no fabricated payments). Efficient and well-structured.
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?
Given no output schema and 3 parameters, the description provides sufficient high-level context: what data it processes, what it reconciles against, and what it does not do. Missing details like error handling, performance implications, or idempotency, but overall adequate for a backfill tool.
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 description mentions a 'trailing window' which loosely relates to as_of_date and lookback_days, but does not explicitly define any parameter semantics. With 0% schema description coverage, the description should compensate but fails to add meaningful details beyond what the schema already shows (names, types, defaults).
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 identifies the tool's verb (materialize, reconcile), resource (past-due instances for recurring obligations), and purpose (to answer whether recurring charges cleared). It distinguishes itself from siblings by specifying its backward-looking and forward-exclusion behavior.
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 usage for reconciling past recurring charges and affects the digest, but it does not explicitly state when to use or when not to use this tool versus alternatives like reconcile_obligation_instances or list_matched_obligation_instances. No exclusions or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
compare_to_legacyA
Parallel-run parity: diff a legacy cash-flow.md against the new daily digest.
Reads the legacy markdown the caller points at (supply a fresh one from your own daily ritual); never runs the legacy ritual or writes any legacy file. Reports matched / missing-in-new / extra-in-new / amount-or-date-changed obligations with a severity each, plus the working-cash delta. Set render_markdown for a short parity summary under the 'markdown' key.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| legacy_cashflow_md_path | Yes | ||
| as_of_date | No | ||
| base_year | No | ||
| render_markdown | No | ||
| db_path | No |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description carries the full burden. It explains the tool reads a legacy markdown, does not modify files, and reports matched/missing/changed obligations with severity and working-cash delta. This provides sufficient transparency into the tool's behavior and non-destructive nature.
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 two paragraphs, front-loading the purpose and then detailing behavior and outputs. It is concise without unnecessary words, though the structuring could be slightly tighter by grouping related info.
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?
For a tool with 5 parameters and no output schema, the description covers the main input and a key output option. It reports the output structure (matched/missing/extra/changed, severity, cash delta) but does not explain all parameters or the output format in detail, leaving some gaps.
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 description coverage is 0%, so the description must compensate. It explains 'legacy_cashflow_md_path' as the source file and 'render_markdown' for a Markdown summary. However, three parameters (as_of_date, base_year, db_path) are left undescribed, leaving gaps in meaning.
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 performs a diff between a legacy cash-flow.md and a new daily digest. It uses specific verbs like 'diff', 'reports', and describes what it reads and does not do, distinguishing it from sibling tools that perform other finance operations.
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 provides explicit usage guidance: supply a fresh legacy markdown, and clarifies that it never runs the legacy ritual or writes any legacy file. It does not explicitly list when not to use or provide alternatives, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
confirm_reconciliation_matchA
Mark a reviewed obligation instance paid using its recorded transaction match. Guarded: requires a recorded match (run reconcile first); never auto-pays. Reversible with unconfirm_reconciliation_match.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| instance_id | Yes | ||
| db_path | No |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool is guarded (requires match), never auto-pays, and is reversible. These are key behavioral traits beyond the obvious mark-paid action. Slightly more detail on side effects or permissions could elevate it, but it is still strong.
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 extremely concise: three sentences that front-load the core purpose, then add usage conditions and reversibility. Every sentence 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and two parameters with 0% coverage, the description is incomplete regarding parameter details and return behavior. However, for a simple confirmation tool, the description covers purpose, prerequisites, and reversibility adequately. Missing parameter docs bring it down.
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 add meaning for the two parameters (instance_id and db_path), but it does not. The description provides no information about what these parameters are, their formats, or how they affect behavior, leaving the schema names to do all the work.
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 marks a reviewed obligation instance as paid using a recorded transaction match. It uses a specific verb ('mark') and resource ('obligation instance'), and distinguishes itself from the sibling tool 'unconfirm_reconciliation_match' by noting reversibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage prerequisites: requires a recorded match (run reconcile first) and notes it never auto-pays. It also mentions the alternative tool for reversal (unconfirm_reconciliation_match), giving clear guidance on when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
dedupe_todoist_recurring_duplicatesB
Cancel future instances of a Todoist-imported obligation that duplicates a proper recurring obligation (e.g. a stale one-off "New York Times" $28.62 vs the recurring "New York Times subscription" $30.30). Conservative subset match; reversible (status -> canceled).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | ||
| db_path | No |
TDQS
B3.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description shoulders the burden of behavioral disclosure. It clearly states that the operation is cancellative (cancel future instances), uses a conservative subset match, and is reversible (status -> canceled). This is good transparency for a tool without annotations, though it does not detail every side effect (e.g., does not affect past instances).
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 relatively concise, using two sentences and a fragment to convey the core purpose, example, and behavior. It is front-loaded with the key action. There is minimal redundancy, though the fragment could be integrated into a single sentence. It earns its place with no wasted words.
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 tool's complexity (deduplication with cancellation of future instances) and the absence of an output schema, the description lacks important context. It does not specify the role of 'as_of_date' (likely a cutoff for future instances), what 'future instances' means, or how duplicates are identified (besides 'conservative subset match'). It also does not reference related sibling tools for further context.
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%, meaning the schema provides no parameter descriptions. The description adds no information about the parameters 'as_of_date' or 'db_path'. The agent has no guidance on what these parameters mean or how to use them, which is critical for a tool with two parameters. The description fails to compensate for the lack of schema 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 tool's purpose: cancel future instances of a Todoist-imported obligation that duplicates a proper recurring obligation. It provides a concrete example with costs, and distinguishes itself from siblings like resolve_todoist_dedup_conflict by clearly stating the action (cancel) and the condition (duplicate).
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 usage (when a duplicate is found) but does not explicitly state when to use this tool vs alternatives. It mentions 'conservative subset match' which provides some guidance, but lacks explicit 'when-to-use' and 'when-not-to-use' directives. Sibling tools like resolve_todoist_dedup_conflict suggest a related but different action, but no comparative guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_finance_memoryB
Delete a finance memory by id (e.g. when a correction is no longer true).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | ||
| db_path | No |
TDQS
B3.2/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It indicates a destructive action (delete), but does not specify whether the deletion is permanent, whether it requires special permissions, or what consequences it has on other data. More detail is needed for safe usage.
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 sentence, which is concise and front-loads the action. However, it could be slightly more structured to separate the action from the example, but overall it is 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?
Given that there is no output schema and 0% schema description coverage, the description is too minimal. It fails to explain return values, error conditions, or prerequisites. A delete operation would benefit from mentioning whether it succeeds silently or returns a confirmation, and any constraints on the memory_id format.
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%, meaning the schema provides no parameter descriptions. The description only indirectly mentions the required parameter (memory_id) via 'by id' but does not explain the optional db_path parameter or provide any formatting or constraints. The description should compensate for the missing schema descriptions.
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 ('delete'), the resource ('finance memory by id'), and provides a concrete example use case ('when a correction is no longer true'). It distinguishes from sibling tools like list_finance_memories, write_finance_memory, and search_finance_memory.
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 gives a specific scenario ('when a correction is no longer true') but does not explicitly state when to avoid using this tool, nor does it compare to alternatives like search_finance_memory for locating the correct id or list_finance_memories for viewing existing records.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
detect_driftB
Detect evidence-backed drift findings, ordered by severity.
Finds missing expected obligations (past due, no matching transaction), stale estimates (review date passed), amount changes (charge happened but differs materially), and unexpected recurring charges (discovered by onboarding but not yet modeled). Deterministic and idempotent. When persist is true, findings are upserted and disappeared ones marked resolved.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | ||
| options | No | ||
| persist | No | ||
| db_path | No |
TDQS
B3.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: determinism, idempotency, ordering by severity, and persistence behavior ('findings are upserted and disappeared ones marked resolved'). Since no annotations are provided, the description compensates well. However, it does not specify the return format (e.g., list of objects) or effects when persist is false.
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 concise (5 short sentences) and front-loads the main purpose. It avoids unnecessary words. Minor improvement could be to structure parameter explanations separately, but current form is efficient.
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?
The description covers the purpose, drift types, and key behavioral aspects. However, missing parameter semantics, no output schema, and lack of usage guidance leave completeness gaps. For a tool with four parameters and complex behavior, more context is needed.
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 description mentions only the 'persist' parameter and its effect. With 0% schema coverage, the description must explain all four parameters but fails to clarify 'as_of_date', 'options', and 'db_path'. It adds no meaning for three out of four parameters.
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 detects 'evidence-backed drift findings' and lists specific types of drift. It uses a specific verb-resource combination ('detect drift findings'). However, it does not explicitly contrast with sibling tools like 'list_drift_findings' to make the distinction obvious, though the purpose is otherwise clear.
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 implies when to use (to find drift) but provides no explicit guidance on when not to use or alternatives. It notes the tool is 'Deterministic and idempotent', which advises repeated use is safe, but does not compare to any sibling tools (e.g., when to use 'apply_guardrail_rules' instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
enqueue_todoist_review_batchA
Record the day's review batch in the durable action outbox. No live write.
Idempotent (one batch per day). dry_run (default true) records the payload without intending to send; dry_run=false marks it pending for a sender that is intentionally not configured. Nothing is ever sent to Todoist here.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | ||
| options | No | ||
| dry_run | No | ||
| db_path | No |
TDQS
A3.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: idempotency (one batch per day), the dry_run effect, and that no Todoist write ever occurs. It also notes the outbox pattern. However, it does not describe failure modes, error handling, or any side effects beyond the outbox recording.
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 front-loaded with the core purpose ('Record the day's review batch'), followed by essential detail in three more sentences. At ~60 words, it is concise and every sentence adds value. Slight room to tighten the dry_run explanation.
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 no output schema and no annotations, the description should cover return values and error conditions. It does not. Two parameters (options, db_path) are undocumented, and the tool's effect on the outbox is vague. The agent lacks enough context to handle all inputs or interpret results.
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?
Parameter schema coverage is 0%. The description explains 'dry_run' and implicitly refers to 'as_of_date' via 'one batch per day', but provides no detail for 'options' or 'db_path'. 'options' is an open object and 'db_path' is unexplained, leaving two parameters semantically opaque.
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 records a review batch in the durable action outbox, is idempotent, and performs no live write. It distinguishes from siblings by explicitly noting 'nothing is ever sent to Todoist here', which contrasts with tools like sync_todoist that actually send data.
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 usage for enqueuing without sending, but lacks explicit when-to-use or when-not-to-use guidance. It does not directly compare with sibling tools like 'preview_todoist_review_batch' or 'execute_action_outbox'. The dry_run parameter is explained, but no alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
evaluate_guardrailsA
Evaluate operating guardrails (cash floor, drift threshold, window age, debt avalanche).
Returns findings ordered by severity. Reads balances and drift from the DB. When persist is true, records the evaluation (pass/fail per rule).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | ||
| persist | No | ||
| db_path | No |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses reading from DB and that persist=true records evaluation, but does not detail side effects, authorization needs, or rate limits. Adequate but not complete.
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?
Three sentences, front-loaded with key purpose, no wasted words. Could be more structured, but efficient.
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 3 parameters (1 required), no output schema, and no annotations, the description provides core functionality but lacks return format details, as_of_date format, and db_path role. Moderately complete.
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%, so the description must compensate. It explains persist behavior, but as_of_date and db_path are not described. Only one of three parameters gains additional meaning.
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 it evaluates operating guardrails (cash floor, drift threshold, window age, debt avalanche) and returns findings ordered by severity. It distinguishes from siblings like apply_guardrail_rules (which applies rules) and list_guardrail_findings (which lists existing findings).
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 usage for evaluating guardrails, but does not explicitly state when to use this tool versus alternatives like list_guardrail_findings or detect_drift. No guidance on when not to use it or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
execute_action_outboxA
Process outbox items. Live Todoist sending is gated OFF by default.
Dry-run items are always simulated. Pending items send to Todoist ONLY when TODOIST_WRITE_ENABLED is set in the finances .env AND a token + project id are configured; otherwise they are marked awaiting-integration (no external call). When enabled, sending is idempotent - one task per outbox key, updated in place on rerun rather than duplicated.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| db_path | No |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and details key behaviors: dry-run simulation, conditional sending, idempotent updates. It explains what happens in different scenarios, though it could mention if any destructive actions occur outside the outbox.
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 concise, with only essential information front-loaded. Each sentence adds distinct value without redundancy or fluff.
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?
While the main behavior is described, the return value or outcome of processing is not mentioned. Additionally, parameter meanings are missing, leaving gaps given no output schema or annotations.
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 0% description coverage for parameters, and the description does not explain what 'options' or 'db_path' mean or how they affect behavior. This leaves significant ambiguity for agent 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 it processes outbox items, with specific details on dry-run vs pending items and Todoist integration. The verb 'process' and resource 'outbox items' are precise, and it distinguishes itself from siblings like list_action_outbox by implying execution rather than listing.
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 provides clear context on when the tool actually sends to Todoist (only when TODOIST_WRITE_ENABLED and configuration exist) and that it is gated off by default. However, it does not explicitly state when not to use it or suggest alternative tools for previewing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_income_instancesC
Generate dated income obligation instances from configured income schedules.
extra_closure_dates accepts YYYY-MM-DD dates imported from a payroll or calendar source for one-off local closures.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| through_date | Yes | ||
| db_path | No | ||
| extra_closure_dates | No |
TDQS
C2.6/5.0
Behavior2/5
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 side effects (e.g., does it create records?), permissions needed, or rate limits. It only notes the format of one parameter, leaving the tool's behavior largely unclear.
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 short with two sentences, but it omits critical details. It is not verbose, but the lack of essential information reduces its value. Every sentence is earned, but more sentences are needed.
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 four parameters, no annotations, and no output schema, the description is incomplete. It fails to explain the return value, side effects, or how the required date parameters are used. A more comprehensive description is necessary.
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 should add meaning to all parameters. It only explains 'extra_closure_dates' format. No information is given for 'start_date', 'through_date', or 'db_path', leaving them ambiguous.
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 that the tool generates dated income obligation instances from configured income schedules. The verb 'generate' and object 'income obligation instances' are specific. However, it does not differentiate from sibling tools that also deal with income sources or obligations.
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 on when to use this tool versus alternatives. It does not mention prerequisites, when not to use, or any context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_background_runC
Return a background run record plus its ordered operation-event log.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| db_path | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only describes the return value, omitting safety traits (e.g., no destructive side effects) or authentication/rate limit considerations.
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, concise but under-specified; it lacks structure and omits critical details, making it less effective than a well-organized brief.
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 two parameters (one optional) and no parameter descriptions, the description fails to provide sufficient context for correct invocation, especially lacking differentiation from sibling tools.
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 has 0% description coverage, and the tool description adds no meaning to the parameters 'run_id' or 'db_path', leaving the agent uninformed about their purpose or format.
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 returns a background run record and its ordered operation-event log, distinguishing it from sibling tools like list_background_runs that likely return only a list.
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 on when to use this tool versus alternatives such as list_background_runs. The description does not mention prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_daily_digestB
The daily finance summary (replaces just daily): balances, cash-flow
projection, upcoming obligations, drift/review items, recurring candidates,
and guardrail status, each with provenance. Set render_markdown for a
cash-flow.md-style narrative under the 'markdown' key. Read-only.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | No | ||
| windows | No | ||
| render_markdown | No | ||
| db_path | No |
TDQS
B3.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool is read-only and explains the behavior of the render_markdown parameter. However, it does not disclose other potential behaviors like data freshness, performance, or side effects. No annotations are provided to supplement.
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 concise, using a single paragraph that front-loads the main purpose and then adds details. It is well-structured with no unnecessary information.
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 lack of an output schema and annotations, the description should provide more detail on the return structure. It lists components but not their format or how they are presented, leaving ambiguity for the agent.
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 coverage, the description only adds meaning for the render_markdown parameter. The other three parameters (as_of_date, windows, db_path) are not described, leaving the agent without guidance on their purpose or usage.
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 provides a daily finance summary with specific components (balances, cash-flow projection, etc.). It is specific about the resource and verb, but does not explicitly differentiate from the many sibling tools, only mentioning it replaces `just daily` which is not a sibling.
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 is the tool for a daily digest, but lacks explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, so the agent must infer context from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_finance_statusC
Return read-only finance status: balances, source freshness, trace ids, and stable V1 slots.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| windows | No | ||
| db_path | No | ||
| working_account_id | No | ||
| start_date | No |
TDQS
C2.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explicitly states 'read-only,' which informs the agent that the tool does not modify state. However, it does not disclose other behavioral traits such as rate limiting, authentication needs, or default behavior when called without parameters.
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 of 13 words, front-loading the purpose ('Return read-only finance status') and listing key output items. Every word adds value, with no fluff or 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?
Given four optional parameters and no output schema, the description is incomplete. It fails to explain parameter usage or output structure beyond a brief list. The agent lacks sufficient context to use the tool effectively, especially for parameterized queries.
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 mention any of the four parameters (windows, db_path, working_account_id, start_date). The agent receives no guidance on the meaning, format, or effect of parameters, leaving a critical gap in usability.
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 returns read-only finance status and lists specific items (balances, source freshness, trace ids, stable V1 slots). It distinguishes the tool as a read-only status retrieval but does not explicitly differentiate from sibling tools, such as other 'get' tools or list 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 specify expected use cases, prerequisites, or exclusions. The user is left without context to choose between this and the many sibling tools (e.g., list_finance_memories, get_daily_digest).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_next_charge_onboarding_candidateB
Return the single highest-priority unresolved charge-onboarding candidate.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states it returns one candidate (non-mutating), but does not disclose whether the call has side effects (e.g., marking the candidate as 'in progress') or any other behavioral traits beyond the return.
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?
A single, front-loaded sentence with no unnecessary words; every word 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?
For a simple getter tool with an output schema, the description is minimal but functional; however, it lacks explanation of the priority order and the optional db_path parameter, which reduces completeness.
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 1 parameter (db_path) with 0% description coverage; the description does not mention or clarify the parameter's purpose, leaving the agent with no guidance on what to provide.
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 clear verb 'Return' and specifies the resource 'charge-onboarding candidate' with qualifiers 'single highest-priority unresolved', making the tool's purpose precise and distinct from sibling tools like 'scan_charge_onboarding_candidates' or 'list_charge_onboarding_queue'.
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 indicates it returns the highest-priority unresolved candidate, implying use in a processing loop, but it does not explicitly state when to use this tool over alternatives like 'list_charge_onboarding_queue' or 'scan_charge_onboarding_candidates', nor does it explain the priority mechanism.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
import_calendar_factsA
Import normalized calendar facts into local storage.
This tool expects source-specific calendar import to happen before the call. Facts should include fact_type, date, source, and optional external_id, calendar_id, related entity, title, confidence, notes, and payload.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| facts | Yes | ||
| db_path | No |
TDQS
A3.5/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only says 'import into local storage' without explaining idempotency, duplicate handling, or whether subsequent calls overwrite or append. Critical behavioral traits are missing.
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 two sentences plus a list, efficiently conveying the purpose and required fields. The list could be better integrated, but overall it is concise and front-loaded.
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 lack of output schema and annotations, the description is incomplete. It does not describe the return value, error handling, or what 'normalized' means. For a tool with a complex array parameter, more detail is needed.
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 description coverage is 0%, so the description must compensate. It lists the expected fields for the 'facts' array (fact_type, date, source, etc.), adding meaning beyond the generic 'additionalProperties: true' schema. However, the 'db_path' parameter is not described, and the structure of each fact object remains vague.
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 'import' and the resource 'normalized calendar facts' into 'local storage'. The tool name and description together distinguish it from sibling import tools like 'import_todoist_obligations'.
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 explicitly states a precondition: 'source-specific calendar import to happen before the call.' This provides clear context for when to use the tool, but does not mention when not to use it or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
import_todoist_obligationsA
Import cashflow-candidate Todoist tasks as canonical one-off obligations.
The local DB stays the source of truth; Todoist is the origin for one-off obligations only. Idempotent by task id. A checked/completed task sets a review date but is never auto-marked paid; a deleted task cancels its instance; a task resembling a recurring obligation is flagged needs_review_dedup_conflict instead of imported. If tasks is omitted, reads cashflow_candidate tasks from the local todoist_tasks snapshot.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | No | ||
| options | No | ||
| db_path | No |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses idempotency, behavior for completed/deleted/recurring-like tasks, and the data flow. It lacks details on return values, error handling, and side effects beyond DB changes, but covers key behavioral traits adequately.
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 paragraph with front-loaded purpose. It efficiently covers multiple edge cases without unnecessary words. Could be slightly more structured (e.g., bullet points), but overall concise and informative.
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?
Input behavior is well-described, but the tool lacks an output schema and the description does not mention return values or error states. For a mutation tool with complex edge cases, this omission reduces completeness. Otherwise, it covers input behavior thoroughly.
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. It explains the 'tasks' parameter (what it should contain, default behavior). However, 'options' and 'db_path' are left undocumented. Partial addition of meaning, but incomplete for all 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?
The description clearly states the tool's purpose: importing Todoist tasks as canonical one-off obligations. It specifies the source (cashflow-candidate tasks), distinguishes from siblings by emphasizing one-off vs. recurring, and explains idempotency and edge cases.
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 provides clear context on when to use the tool (for importing one-off obligations from Todoist) and implies limitations (local DB as source of truth, only for one-off). It does not explicitly state when not to use or compare to siblings, but the behavioral details offer sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_action_outboxC
List durable action-outbox items (intended external writes) and their status.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| db_path | No |
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility but only states the basic operation. It does not indicate whether the operation is read-only, any required permissions, or other behavioral traits beyond listing and status.
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 very concise (one sentence) and front-loaded. However, it lacks structure and could benefit from more detail without being verbose.
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 lack of output schema and annotations, and the presence of two undocumented parameters, the description is incomplete. It fails to explain what 'action-outbox' items are, possible statuses, or the nature of the returned list.
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 the 'status' or 'db_path' parameters. The parameters are left entirely undocumented, adding no meaning beyond the raw schema.
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 identifies the tool as listing durable action-outbox items and their status, with a specific verb and resource. It distinguishes itself from siblings by focusing on 'action-outbox items' which is unique among the many 'list_*' 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?
No guidance is provided on when to use this tool versus alternatives. Among numerous sibling tools with similar prefixes, no context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_background_runsC
List recent background runs with their status and timing.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run_type | No | ||
| status | No | ||
| limit | No | ||
| db_path | No |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'list recent' without defining recency, ordering, pagination, or side effects. Vague.
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?
Single concise sentence, but lacks necessary details about parameters and behavior. Under-specified.
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?
With 4 parameters, no output schema, and no annotations, the description is incomplete. Lacks info on return value and how parameters affect results.
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?
0% schema coverage and description does not explain any of the 4 parameters (run_type, status, limit, db_path). Agents must infer from parameter names alone.
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 it lists background runs with status and timing, distinguishing it from sibling 'get_background_run' which retrieves a single run.
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 on when to use this tool vs alternatives like 'get_background_run' or other list tools. Conditions for usage are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_calendar_factsC
List local normalized calendar facts with optional filters.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fact_type | No | ||
| start_date | No | ||
| through_date | No | ||
| status | No | active | |
| related_entity_type | No | ||
| related_entity_id | No | ||
| db_path | No |
TDQS
C2.1/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose read-only nature, return format, side effects, or any constraints. 'List' implies a read operation, but without annotations, this is insufficient for an agent to understand behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but too minimal. It lacks front-loaded key information, such as what a 'calendar fact' is, and does not earn its place by providing sufficient detail.
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 no annotations, no output schema, and 7 undocumented parameters, the description is wholly inadequate. It does not explain the concept of 'calendar facts', 'normalized', or the nature of filters, leaving the agent with little to no context for correct invocation.
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%, yet the description only states 'optional filters' without explaining any of the 7 parameters. Parameter names like 'fact_type' and 'status' are partially self-explanatory, but the description adds no meaning beyond the schema.
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 verb (list) and resource (local normalized calendar facts), which is specific. It distinguishes from siblings like 'import_calendar_facts' by its action, but does not explicitly differentiate from other list 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?
No guidance on when to use or avoid this tool versus alternatives like 'list_obligations'. The phrase 'optional filters' does not clarify which sibling tools serve similar filtering purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_charge_onboarding_queueA
List charge-onboarding candidates ordered by estimated monthly cash impact.
By default returns only the active queue (candidates still awaiting a decision). Pass status to filter exactly, or include_resolved=True to see decided/paused candidates such as deferred or rejected ones.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| limit | No | ||
| include_resolved | No | ||
| db_path | No |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains ordering, default filtering, and parameter usage. No side effects discussed, but it's a read operation. Lacks mention of pagination 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words.
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?
Adequately covers ordering and filtering. Missing details on pagination, output format, or behavior of 'limit' and 'db_path'.
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 description must compensate. It explains 'status' and 'include_resolved', but not 'limit' or 'db_path'. 'db_path' is unusual and left unexplained, so only half the parameters are covered.
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 'list' and resource 'charge-onboarding candidates', orders by monthly cash impact, and clearly distinguishes from sibling list tools by focusing on charge-onboarding candidates.
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 default behavior (active queue), how to filter by status or include resolved candidates. It does not explicitly state when to use alternatives, but context with siblings makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_drift_findingsC
List stored drift findings, filtered by status (default active) and type.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | active | |
| finding_type | No | ||
| db_path | No |
TDQS
C2.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It indicates a read-only list operation but omits details about pagination, result ordering, error handling, or whether the tool triggers side effects. The behavior is minimally described.
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 extremely concise with a single sentence that delivers the essential information: what the tool does and its primary filters. It is front-loaded and contains no 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?
The tool has 3 parameters and no output schema or annotations. The description covers only two filters, leaving the 'db_path' parameter unexplained. It does not describe the return format, pagination, or any behavioral nuance, making it incomplete for an agent to use effectively.
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%, so the description must compensate. It mentions the 'status' and 'finding_type' parameters with default values but does not explain their allowed values or formats. The third parameter 'db_path' is entirely unmentioned, leaving its purpose and usage unclear.
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 verb 'list' and the resource 'stored drift findings.' It specifies two filters (status with default 'active' and type), which conveys the tool's scope and differentiates it from related tools like 'detect_drift' that create findings. However, it does not explicitly distinguish from sibling list tools like 'list_guardrail_findings.'
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 versus alternatives, such as 'list_guardrail_findings' or 'detect_drift.' There is no mention of prerequisites, limitations, or best practices. The agent must infer usage from the context of drift findings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_finance_memoriesC
List stored finance memories, optionally filtered by kind.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| limit | No | ||
| db_path | No |
TDQS
C2.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the burden. It only says 'list', implying read-only, but doesn't disclose if there are side effects, permission needs, or behavior with parameters like db_path. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that is front-loaded. It is not verbose, though additional structured details would improve clarity without sacrificing conciseness.
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 no output schema, no annotations, and three parameters with zero schema descriptions, the description is incomplete. It lacks definition of finance memories, kind values, limit behavior, and db_path purpose.
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%, so the description must explain parameters. It only mentions 'kind' filter but doesn't define valid values or explain 'limit' or 'db_path'. Two of three parameters are undocumented.
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 verb 'list' and the resource 'finance memories', and mentions an optional filter by kind. This differentiates it from siblings like list_obligations or list_income_sources, though it doesn't clarify what a finance memory is versus search_finance_memory.
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 on when to use this tool versus alternatives like search_finance_memory or write_finance_memory. No prerequisites or context provided for effective use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_guardrail_findingsC
List recorded guardrail evaluations, optionally filtered by date or rule.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| evaluation_date | No | ||
| rule_type | No | ||
| db_path | No |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states the action (list) without disclosing side effects, read-only nature, or any behavioral traits. Agent cannot infer safety or cost implications.
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, front-loaded sentence that efficiently states the core function. However, it is perhaps too concise and could benefit from additional context without becoming verbose.
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 tool has 3 optional parameters, no output schema, and no annotations, the description is insufficient. It does not explain return format, the meaning of guardrail evaluations, or the purpose of db_path.
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%, so description must add meaning. It mentions filters by date or rule, corresponding to evaluation_date and rule_type, but completely ignores the db_path parameter. This leaves one parameter unexplained.
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 'list' and the resource 'recorded guardrail evaluations', and mentions optional filters by date or rule. This distinguishes it from siblings like list_drift_findings and evaluate_guardrails.
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 versus alternatives such as list_drift_findings or evaluate_guardrails. There are no prerequisites or 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.
list_income_sourcesC
List configured income sources, schedule versions, review dates, and generated horizons.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | No |
TDQS
C2.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It does not explicitly state that the tool is read-only or idempotent, but as a list operation it is reasonably safe. No mention of authentication, rate limits, or data freshness.
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 sentence, front-loading the action and key entities. However, it could be more concise by avoiding the list of items if they are not all equally important.
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 absence of an output schema and many sibling tools, the description is too sparse. It doesn't explain the relationship between income sources and the other listed items, nor does it describe the output format. The agent may have difficulty interpreting the results.
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%, so the description must explain the parameter 'db_path'. It does not. The parameter is optional and defaults to null, but the agent gets no hint about its purpose or effect on the results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool lists configured income sources plus related items (schedule versions, review dates, generated horizons), but it's ambiguous whether it lists multiple distinct entities or all these details for each income source. The verb 'List' is clear, but the scope is broader than the name implies.
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 on when to use this tool versus the many sibling list tools (e.g., list_obligations, list_guardrail_findings). The description provides no context about scenarios or prerequisites, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_matched_obligation_instancesC
List obligation instances matched to a transaction, with score and evidence.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| match_type | No | ||
| db_path | No |
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description minimally states the output includes score and evidence but says nothing about behavior like pagination, idempotency, or side effects. For a list operation, more detail is expected.
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, very concise, but at the expense of completeness. It is front-loaded but under-specified.
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 lack of output schema and only two optional parameters, the description fails to explain 'matched' context, transaction reference, or how parameters affect results. It is incomplete for productive use.
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 adds no explanation of what the two optional parameters (match_type, db_path) do. The agent has no guidance on how to use them.
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 lists obligation instances matched to a transaction with score and evidence, specifying the action and resource. However, it does not differentiate from sibling tools like list_unmatched_obligation_instances, but the mention of 'matched' provides necessary context.
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 versus alternatives, nor any prerequisites or exclusions. The description lacks context on typical use cases or situations to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_obligation_review_candidatesC
List obligation instances that need review, such as estimated amounts due for refresh.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | ||
| db_path | No |
TDQS
C2.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. Only states it lists instances needing review; does not mention if it is read-only, required permissions, or any side effects. For a listing operation, read-only is assumed but not confirmed.
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?
Single sentence, very concise. Front-loaded with the purpose. No wasted words, though could benefit from parameter details.
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 two simple parameters and no output schema, description is incomplete. Does not specify return format, filtering behavior, or parameter purpose. Minimal context for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero description coverage for parameters. Description does not explain as_of_date or db_path. No added value beyond the schema's type and nullability.
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 obligation instances needing review, with an example 'estimated amounts due for refresh'. This is specific and distinguishes from sibling tools like list_obligations which list all instances.
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 on when to use this tool versus alternatives (e.g., list_obligations, list_matched_obligation_instances). The example implies a scenario but no explicit when/when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_obligationsC
List local canonical obligations and optionally their dated instances.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| status | No | active | |
| include_instances | No | ||
| db_path | No |
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It only says 'list' implying read-only, but provides no additional behavioral context such as pagination, default filters, or what 'local canonical' means.
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?
Single sentence, very concise but sacrifices detail. It is not overly verbose, but the brevity leaves gaps.
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 4 parameters, no output schema, and numerous sibling tools, the description is incomplete. It fails to explain what comprises an obligation, how instances are returned, or how to interpret defaults like status=active.
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 has 0% description coverage. The description only hints at the 'include_instances' parameter via 'optionally their dated instances'. It provides no explanation for the other three parameters (kind, status, db_path) which are not self-explanatory.
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?
Description clearly states the tool lists 'local canonical obligations' and optionally their dated instances, which is specific. However, it does not explicitly differentiate from siblings like list_matched_obligation_instances or list_unmatched_obligation_instances, but the purpose is reasonably clear.
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 on when to use this tool versus alternatives. There are many sibling list tools, but the description does not specify the context or constraints for using this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_reconciliation_review_itemsB
List recorded transaction matches whose obligation instance still awaits confirmation (the day's close-out queue). Read-only.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | No | ||
| db_path | No |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It correctly states 'read-only', indicating no state change, which is a key behavioral trait. However, it does not disclose other aspects like return format, pagination, or authorization requirements.
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 sentence with no wasted words. It is front-loaded with the action and condition. It is efficient but could benefit from slight expansion for clarity.
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 no output schema and no annotations, the description is minimal. It omits the return structure, parameter details, and usage context. For a tool that lists items, more completeness is needed to guide the agent.
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%, so the description must add meaning to the parameters (as_of_date, db_path). It does not mention them at all, leaving the agent to infer their purpose from names alone. This 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?
The description clearly specifies the verb 'list', the resource 'recorded transaction matches', and the condition 'awaiting confirmation' with context 'the day's close-out queue'. It also includes 'read-only'. This distinguishes it from siblings like list_matched_obligation_instances.
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 usage for the close-out queue but does not explicitly state when to use this tool versus alternatives like confirm_reconciliation_match or list_matched_obligation_instances. No exclusions or comparative guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_statement_cyclesC
List statement cycles for a card obligation with their aggregated card-input evidence.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target_obligation_id | Yes | ||
| db_path | No |
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not explicitly state that the tool is read-only or non-destructive. While 'list' implies a read operation, the lack of explicit behavioral disclosure (e.g., no side effects, auth requirements) is a gap given the absence of annotations.
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 concise sentence (13 words), which is efficient, but it omits critical information about parameters and usage. It is not verbose, but it sacrifices completeness for brevity.
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 clarify what the tool returns. It mentions 'aggregated card-input evidence' but this is vague. The description does not explain the output format, pagination, or how the aggregation works, leaving the agent with significant unknowns.
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%, so the description should explain the parameters. It mentions 'card obligation' but does not describe 'target_obligation_id' or 'db_path'. The required parameter lacks explanation, and the optional parameter's purpose is unclear.
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 it lists statement cycles for a card obligation with aggregated card-input evidence. The verb 'list' and resource 'statement cycles' are explicit, and the additional context about aggregation helps distinguish it from siblings like 'list_statement_input_estimates' or 'list_obligations'.
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 usage guidance is provided. The description does not specify when to use this tool over alternatives, nor does it mention any prerequisites or exclusion criteria. Sibling tools exist but no comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_statement_input_estimatesC
List card-spend inputs that feed future statement estimates without directly reducing checking.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target_obligation_id | No | ||
| start_date | No | ||
| through_date | No | ||
| status | No | expected | |
| db_path | No |
TDQS
C2.7/5.0
Behavior2/5
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 only mentions one behavioral aspect ('without directly reducing checking') but omits other important traits like read-only nature, side effects, or prerequisites.
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, concise sentence that front-loads the action. While it could add parameter info without becoming verbose, it is efficient and to the point.
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 the tool has 5 parameters with no schema descriptions and no output schema, the description is severely incomplete. It fails to explain parameters, return format, or context of use, leaving the agent with insufficient information.
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 description does not mention any of the 5 parameters. Schema description coverage is 0%, so parameters are completely undocumented. The agent receives no help on parameter meaning, values, or 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 verb 'list' and the resource 'card-spend inputs that feed future statement estimates'. It adds a distinguishing behavioral trait: 'without directly reducing checking', which differentiates it from similar listing 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?
No explicit guidance on when to use this tool versus alternatives. The description implies a specific context (future statement estimates not affecting checking) but doesn't mention when not to use or compare to siblings like aggregate_statement_inputs or list_statement_cycles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_todoist_sync_recordsC
List Todoist-to-obligation sync records, optionally filtered by status or task id.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sync_status | No | ||
| external_task_id | No | ||
| db_path | No |
TDQS
C2.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose behavioral traits such as that the operation is read-only, has no side effects, or any authentication requirements. It only implies a list operation without explicit safety information.
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?
A single sentence of 10 words conveys the core purpose and optional filters. Every word is necessary; no wasted text. 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?
The tool is simple (list with filters) but the description does not hint at what is returned (e.g., fields of sync records). With no output schema, more detail on return values would improve completeness.
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 description adds meaning for two parameters ('sync_status' and 'external_task_id') by mentioning optional filtering, but completely omits the third parameter 'db_path'. Given 0% schema description coverage, the description only partially compensates.
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 it lists 'Todoist-to-obligation sync records' with optional filters, using a specific verb and resource. It distinguishes from sibling tools like 'import_todoist_obligations' or 'sync_todoist' by focusing on listing existing records, but does not explicitly contrast with other list 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 or when not to use it. With many siblings, such as 'list_obligations' or 'list_matched_obligation_instances', explicit usage context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_unmatched_obligation_instancesC
List expected obligation instances with no matching transaction (drift inputs).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| past_grace_only | No | ||
| db_path | No |
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It only states what the tool lists, but does not mention whether it is read-only, idempotent, safe, or any side effects. The term 'drift inputs' is jargon and not explained.
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, making it concise, but it sacrifices important details. It could be restructured to front-load the core purpose and then add brief parameter explanations.
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 no output schema, no annotations, and two undocumented parameters, the description is insufficient for an agent to use the tool correctly. Additional context about return format, default behaviors, and parameter effects is needed.
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 coverage is 0%, and the description adds no meaning for the two parameters ('past_grace_only', 'db_path'). The agent receives no guidance on their semantics, expected values, or effect on results.
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 action ('list') and the resource ('expected obligation instances with no matching transaction'), and adds context ('drift inputs'). However, it does not differentiate from sibling tools like 'list_matched_obligation_instances' or 'list_obligation_review_candidates', which could cause confusion.
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 versus alternatives. The description does not mention prerequisites, typical use cases, or cases where another sibling tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
preview_charge_onboarding_applyA
Preview the canonical obligation and dated instances that applying would create.
Read-only and writes nothing. Use this to show a reviewer exactly what would land in the cash-flow model (obligation, instances, schedule summary, and warnings) before committing to apply.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| candidate_id | Yes | ||
| start_date | No | ||
| through_date | No | ||
| horizon_days | No | ||
| obligation_id | No | ||
| db_path | No |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Read-only and writes nothing,' which is a key behavioral trait. It also mentions what the output includes (obligation, instances, schedule summary, warnings). Without annotations, this is helpful, though it lacks details on auth or error 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?
The description is two concise sentences, front-loading the key point. Every sentence adds value with no waste.
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 6 parameters and no output schema, the description provides a high-level overview but lacks details on return format or parameter interplay. It mentions output components but not their structure, making it adequate but not fully complete.
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 description does not explain any parameters. With 0% schema description coverage, the agent must infer parameter semantics from context. The description only mentions the overall preview purpose, not how candidate_id, dates, or horizon_days affect the output.
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 what the tool does: 'Preview the canonical obligation and dated instances that applying would create.' It uses specific verbs and resources, and distinguishes from siblings like 'apply_charge_onboarding_candidate' by emphasizing it is a read-only preview.
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 says 'Use this to show a reviewer exactly what would land in the cash-flow model before committing to apply,' which provides a clear use case. It implicitly guides when to use this tool over the apply tool, but could be more explicit about 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.
preview_todoist_review_batchA
Render the day's review items (drift findings) as a Todoist task + subtasks.
Read-only and sends nothing. Returns the parent task and per-item subtasks with specific guidance, so the user can see the review batch before any write.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | ||
| options | No | ||
| db_path | No |
TDQS
A4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that the tool is 'Read-only and sends nothing,' clearly indicating no side effects. It also describes the return value: 'Returns the parent task and per-item subtasks with specific guidance.' Since no annotations are provided, the description fully shoulders the behavioral transparency burden and does so effectively.
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 concise (three sentences) and front-loaded with the core action. Each sentence adds meaningful information: what it does, its read-only nature, and what it returns. No extraneous words or redundancy.
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?
While the description covers purpose, read-only behavior, and return structure, it lacks important context: parameter details (especially the free-form 'options' object), prerequisite conditions (e.g., reliance on drift findings from detect_drift), and more precise output format. Without an output schema, additional detail on 'specific guidance' would be helpful. The description is adequate but incomplete for full understanding.
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 3 parameters with 0% description coverage. The description does not explain 'as_of_date', 'options', or 'db_path'. It only indirectly implies that 'as_of_date' is used for 'the day's review items,' but lacks format details. 'options' and 'db_path' are completely undocumented. The description fails to compensate for the schema's lack of parameter descriptions.
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 purpose: 'Render the day's review items (drift findings) as a Todoist task + subtasks.' It specifies the action (render), the resource (review items/drift findings), and the output format (Todoist task + subtasks). The tool name and description align, and it is distinguishable from sibling tools like enqueue_todoist_review_batch.
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 usage context by stating 'so the user can see the review batch before any write,' suggesting it should be used prior to write operations. However, it does not explicitly state when to use this tool versus alternatives (e.g., enqueue_todoist_review_batch), nor does it provide exclusions or prerequisites. The guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
recompute_statement_estimatesA
Fill unconfirmed statement estimates from the card-input rollup, guarded.
Only statement instances whose amount is an unconfirmed projection are recomputed, as baseline (expected non-modeled card spend) plus the rolled-up modeled card inputs for that cycle. Portal/observed amounts are never overwritten. Idempotent.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target_obligation_id | Yes | ||
| baseline | No | ||
| db_path | No |
TDQS
A4.3/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key traits: idempotent, does not overwrite portal/observed amounts, only recomputes unconfirmed projections, and uses a baseline plus rolled-up modeled card inputs. This gives the agent a thorough understanding of the tool's 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?
The description is exceptionally concise, with three sentences that front-load the core purpose and then add necessary details. Every sentence adds value—no redundancy or filler.
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?
Given no output schema and moderate complexity, the description covers the key aspects: conditions, behavior, and idempotency. However, it assumes domain knowledge (e.g., 'card-input rollup') and doesn't explain results or edge cases, leaving minor gaps for a complete understanding.
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, but it only mentions 'baseline' without defining it or explaining 'target_obligation_id' or 'db_path.' The term 'baseline' is used but not linked to the parameter, and the other parameters lack any semantic clarification. This leaves significant ambiguity for the agent.
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 purpose: 'Fill unconfirmed statement estimates from the card-input rollup, guarded.' It specifies the resource (statement estimates) and the action (recomputing) with constraints (only unconfirmed, never overwrite portal/observed). This distinguishes it from siblings like 'list_statement_input_estimates' or 'reconcile_obligation_instances'.
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 provides clear conditions for use: 'Only statement instances whose amount is an unconfirmed projection are recomputed' and 'Portal/observed amounts are never overwritten.' While it doesn't explicitly name alternatives, the constraints effectively guide when to use this tool versus others, making the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reconcile_obligation_instancesA
Match expected obligation instances against observed transactions.
Deterministic and idempotent. Records the best transaction match per instance as review evidence (amount + date + merchant scoring). Conservative by default: matches are not silently marked paid (set options.auto_mark_paid to opt in), unmatched past-grace instances become needs_review not overdue (set options.flag_unmatched_needs_review to opt in), and card-statement-input instances are skipped (they settle via the statement, not a checking match).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | ||
| options | No | ||
| db_path | No |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses key behavioral traits: deterministic, idempotent, conservatively defaults (no auto-mark paid, no flag unmatched), skips card-statement-input instances, and records best match as evidence. It adds value beyond just naming the operation, though side effects on data are not explicitly stated.
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 concise with three sentences. First sentence states purpose, second details properties, third explains defaults. No redundant information; every sentence earns its place.
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?
The description covers core behavior and defaults, but omits the return value (what the function returns after recording matches) and prerequisites (e.g., obligation instances must exist). For a tool with moderate complexity and no output schema, these omissions reduce completeness.
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%, so description must compensate. It adds meaning for the options parameter by describing auto_mark_paid and flag_unmatched_needs_review, but does not explain as_of_date or db_path. Coverage is incomplete for a 3-parameter tool, leaving significant gaps.
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 matches expected obligation instances against observed transactions, using a specific verb and resource. It distinguishes from sibling tools like confirm_reconciliation_match and list_matched_obligation_instances by describing its role as the initial matching step that records evidence.
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 context on when to use the tool by explaining its deterministic, idempotent nature and conservative defaults, but lacks explicit guidance on when to use this versus alternatives like confirm_reconciliation_match. It implies usage context but does not state exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
record_charge_onboarding_decisionA
Record a review decision against a charge-onboarding candidate.
Supported actions in this slice: defer, reject, needs_more_evidence, in_review, reset. Applying a candidate into a canonical obligation (accept/apply) or restructuring (merge/split) is a separate guarded slice and is rejected here.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| candidate_id | Yes | ||
| decision | Yes | ||
| db_path | No |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly discloses that accept/apply/merge/split decisions are rejected, and lists the supported actions. However, it does not describe potential side effects (e.g., overwriting previous decisions), required permissions, or the lifecycle after recording.
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: the first states the primary purpose, the second adds necessary constraints. No redundant information, well-structured.
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 moderate complexity (nested object params, no output schema, no annotations), the description covers the main action and exclusions but falls short on parameter details. An agent would need additional context to properly construct the 'decision' object.
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 provides almost no parameter-level guidance. The 'decision' parameter is an object with additionalProperties true, but the description only lists action strings without clarifying the required structure or any additional fields. 'candidate_id' is mentioned only implicitly. This is insufficient for 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 action ('Record a review decision') and resource ('charge-onboarding candidate'). It lists supported actions (defer, reject, needs_more_evidence, in_review, reset) and explicitly differentiates from the sibling tool 'apply_charge_onboarding_candidate' by stating that accept/apply/merge/split are rejected here.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (for decisions like defer, reject, etc.) and when not to (for accept/apply/merge/split, which are handled by a separate guarded slice). This provides clear guidance on selection versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolve_todoist_dedup_conflictC
Resolve a flagged Todoist dedup conflict: import_anyway, skip, or merge.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| external_task_id | Yes | ||
| decision | Yes | ||
| merge_with_obligation_id | No | ||
| db_path | No |
TDQS
C2.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states that the tool resolves a conflict. It does not disclose behavioral traits such as whether the operation is destructive, what state changes occur, auth requirements, or error handling. This leaves the agent without critical context.
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, making it concise, but it sacrifices necessary detail. It is front-loaded with the purpose, but every word is not optimally used; for example, listing decision values without explaining when each is appropriate reduces efficiency.
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 that there are 4 parameters (2 required), no output schema, and no annotations, the description should provide more context about tool behavior, return values, and how to use parameters. It only covers the basic resolution action, leaving significant gaps for the 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%, and the description adds almost no meaning beyond the parameter names. It only mentions the decision options ('import_anyway, skip, or merge'), but fails to explain the role of 'external_task_id', 'merge_with_obligation_id', or 'db_path'. The agent would be forced to infer or guess.
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 identifies the tool's action (resolve) and resource (Todoist dedup conflict), listing the possible decisions. However, it does not differentiate from sibling tools like 'dedupe_todoist_recurring_duplicates' or 'enqueue_todoist_review_batch', which limits clarity for the agent.
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 explicit guidance on when to use this tool versus alternatives. The description implies it is used after a conflict is flagged, but does not state prerequisites, when not to use it, or how it relates to other Todoist-related sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_background_syncB
Run the finance pipeline as one auditable background run.
Orchestrates: scan charge candidates, reconcile transactions, detect drift, and preview the Todoist review batch (dry run). Records a run record plus an ordered operation-event log. A failing step is logged and the run continues (partial_success). Returns the run id, trace id, status, and step summaries.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | ||
| options | No | ||
| run_type | No | daily_sync | |
| trigger_type | No | manual | |
| db_path | No |
TDQS
B3.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses partial_success behavior (failing step logged, run continues) and return fields (run id, trace id, status, step summaries). However, no annotations are provided, and details on side effects, idempotency, or rate limits are absent.
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 concise, with two brief paragraphs that front-load the purpose and then detail orchestrated steps and behavior. It could be tighter by avoiding redundancy with sibling tool names, but overall 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?
Given 5 parameters and no output schema, the description lacks essential context on parameter semantics and return details beyond a brief mention. Error handling beyond partial_success is not covered, and the tool's relationship to many sibling tools is only implied.
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 any of the 5 parameters (as_of_date, options, run_type, trigger_type, db_path). The description fails to explain parameter meaning, format, or 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 tool runs the finance pipeline as an auditable background run, and lists the orchestrated steps (scan, reconcile, detect drift, preview). This distinguishes it from sibling tools that are individual steps.
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 usage for running the full pipeline by listing orchestrated steps, but does not explicitly state when to use this vs individual step tools, nor provides exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_live_validationA
Validate the pipeline on live data without touching the committed snapshot.
Copies the database to a throwaway working DB, optionally pulls live SimpleFIN
Todoist into the copy, then runs the read pipeline (onboarding scan, reconciliation, drift, guardrails) and returns a report with integrity checks (e.g. no orphaned statement targets after a card rename). The source database is never mutated.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | ||
| sync | No | ||
| keep_work_db | No | ||
| db_path | No |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: source database is never mutated, a throwaway working DB is used, optional live data pull, and the read pipeline runs returning a report. This is thorough, though it could mention cleanup of the working DB or error handling.
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 concise, using three well-structured sentences. The first sentence states the core purpose, followed by operational details. No unnecessary words or repetition.
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 absence of an output schema and annotations, the description covers the tool's purpose, safety, and basic workflow. However, it lacks detail on the report's format, parameter roles, and post-conditions like cleanup, leaving some gaps for a complex tool with four parameters.
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 0% description coverage, and the tool description only hints at the 'sync' parameter with 'optionally pulls live SimpleFIN + Todoist'. It does not explain 'as_of_date', 'db_path', or 'keep_work_db' sufficiently. With low schema coverage, the description should compensate with detailed parameter semantics but falls short.
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 validates the pipeline on live data without touching the committed snapshot, using a throwaway copy. This distinguishes it from sibling tools that mutate data (e.g., apply_*, sync_*), making the purpose 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for validation without side effects, but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The context is clear but lacks explicit directives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
scan_charge_onboarding_candidatesA
Scan transaction history and discover reviewable charge-pattern candidates.
This is the background-discovery entry point: it groups related transactions by merchant and account, proposes schedule/amount/cash-impact/review policies, and stores durable candidates in a review queue. It is idempotent and never writes canonical obligations or moves cash flow. Options support min_evidence, include_inflows, and link_existing_obligations.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| db_path | No |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behaviors: idempotent, never writes canonical obligations, never moves cash flow, and stores durable candidates. Without annotations, it provides good transparency, though it could elaborate on what exactly 'durable candidates' entails in terms of storage and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: first sentence states the action, second provides context, and the last line lists options. No extraneous information, every sentence adds value.
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?
Given the tool's complexity and lack of output schema, the description covers purpose, key behaviors, and options. It could mention how to retrieve the generated candidates (e.g., via 'list_charge_onboarding_queue'), but it's largely complete for a background-discovery tool.
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?
The description adds meaning to the 'options' parameter by listing supported fields (min_evidence, include_inflows, link_existing_obligations). However, with 0% schema coverage and two parameters, the 'db_path' parameter remains unexplained, so the description only partially compensates for the missing schema descriptions.
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 scans transaction history to discover charge-pattern candidates, groups transactions, and stores candidates in a queue. It identifies itself as the background-discovery entry point, distinguishing it from sibling tools like 'list_charge_onboarding_queue' and 'apply_charge_onboarding_candidate'.
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?
Describes the tool as an entry point and notes idempotency and no writes to obligations or cash movement, implying it's a safe first step. However, it does not explicitly state when to use versus alternatives or provide any when-not guidance, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_finance_memoryA
Retrieve the most relevant finance memories for a query, under a context policy.
Records are scored by similarity, then filtered by min_score, capped at k, and bounded by a max_tokens budget. The result reports how many records each limit dropped so the amount of memory entering context is explicit.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| k | No | ||
| min_score | No | ||
| max_tokens | No | ||
| kind | No | ||
| db_path | No |
TDQS
A4.3/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully handles behavioral disclosure. It explains the scoring, filtering by min_score, capping at k, bounding by max_tokens, and reporting of dropped records. This is comprehensive for a read-only retrieval tool.
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 three sentences: first states purpose, second explains the process, third details the result. No redundant information; 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 tool has 6 parameters and no output schema, the description covers core behavior (ranking, filtering, capping) and result reporting. However, it omits explanation of 'db_path', 'kind', and 'context policy', and does not describe the return format. This leaves gaps for a complete understanding.
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?
With 0% schema description coverage, the description adds some value by explaining the overall process (scored, filtered, capped) but does not elaborate on specific parameters like 'kind' or 'db_path'. It adds meaning beyond the schema but not enough to fully compensate for the lack of param descriptions.
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 retrieves relevant finance memories for a query, using a specific verb 'retrieve' and resource 'finance memories'. This distinguishes it from sibling tools like 'list_finance_memories' which lists all memories without ranking.
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 provides clear context on when to use the tool: for retrieving memories under a context policy with similarity scoring and filtering. However, it does not explicitly state when not to use it or mention alternative tools like 'list_finance_memories'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
summarize_spendingA
Summarize outflow spending over a date range, grouped by category, merchant, or month: totals, counts, top buckets, a month-over-month trend, and the transaction ids behind each bucket. Transfers and income are excluded by default. Read-only. Set render_markdown for a summary under 'markdown'.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | Yes | ||
| group_by | No | category | |
| exclude_transfers | No | ||
| render_markdown | No | ||
| db_path | No |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Read-only' and explains default exclusions, providing behavioral context beyond the input schema. However, it could mention additional traits like data limits or response 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 concise (three sentences) and front-loaded with the core purpose. Every sentence adds value, no fluff or repetition.
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?
Given no output schema and no annotations, the description provides a solid overview of inputs and output components (totals, counts, top buckets, trend, transaction ids). It lacks details on output format and error conditions, but is sufficient for an agent to understand the tool's basic behavior.
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?
With 0% schema description coverage, the description compensates by explaining most parameters (date range, grouping, exclusion defaults, render_markdown). The db_path parameter is not explained, but it's optional and relatively self-evident.
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 purpose: 'Summarize outflow spending over a date range' with specific grouping options and output details, distinguishing it from siblings that are more about listing or importing data.
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 usage context (e.g., excludes transfers and income by default, use render_markdown for markdown output) but does not explicitly name alternatives or specify when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sync_simplefinA
Pull live accounts, balances, and transactions from SimpleFIN into the DB.
Reads SIMPLEFIN_ACCESS_URL from the finances .env at runtime (never returned). Read-only against SimpleFIN; idempotent upsert by transaction id. When start_date is omitted, incremental=true resumes from the last synced transactions (cheap for a daily run); otherwise it pulls lookback_days (SimpleFIN caps the window at 90 days). Returns counts and any warnings.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | ||
| end_date | No | ||
| lookback_days | No | ||
| incremental | No | ||
| db_path | No |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature against SimpleFIN, idempotent upsert, reading env var, and return value (counts and warnings). Lacks details on error handling or rate limits, but generally transparent.
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?
Five sentences, front-loaded with main action, each sentence adds value with no redundancy or fluff.
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?
No output schema, but description mentions return counts and warnings. Covers main parameters and behavior. Could elaborate on db_path and end_date, but overall sufficient for a sync tool with 5 params.
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%, but description explains start_date, incremental, and lookback_days behavior (e.g., incremental reset when start_date given). However, end_date and db_path are not described. Partially compensates for missing schema descriptions.
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 pulls live accounts, balances, and transactions from SimpleFIN into the DB, using specific verb and resource. It distinguishes from sibling tools like sync_todoist or list_statement_cycles.
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?
Explains when to use incremental vs start_date, mentions SimpleFIN's 90-day cap, and that incremental resumes from last sync. Does not explicitly mention when not to use or alternatives, but provides clear context for choosing parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sync_todoistA
Pull the live Todoist board (tasks + sections) into the local DB, read-only.
Reads TODOIST_API_TOKEN and the project id from the finances .env / obligations.yaml at runtime (never returned). Normalizes each task into the cashflow fields the onboarding importer uses, upserts by id, and marks tasks no longer seen as deleted. Does NOT write to Todoist.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | No |
TDQS
A3.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description fully discloses reading env vars, not returning secrets, upserting, marking deleted, and that it does not write to Todoist. Comprehensive for a read sync.
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?
Three sentences, front-loaded with purpose. Efficient but could be slightly tighter. Still well-structured.
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?
Covers main behavior but omits behavior for default db_path (null case). No output schema or annotation context, so a bit of gap exists.
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 only parameter db_path (optional, default null) is not mentioned in the description. With 0% schema coverage, the description fails to add any meaning beyond the schema, which is itself minimal.
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 it pulls Todoist board into local DB, read-only, and normalizes tasks. It distinguishes from siblings like import_todoist_obligations by syncing the full board.
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?
States when to use (sync Todoist board) and that it's read-only. Does not explicitly exclude alternatives or provide when-not-to-use guidance, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
unconfirm_reconciliation_matchB
Reverse a confirmation: return the obligation instance to 'expected' and clear the matched-transaction evidence.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| instance_id | Yes | ||
| db_path | No |
TDQS
B3.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the main behavioral effect (reversal, state change, clearing evidence), but does not elaborate on safety, permissions, reversibility, or constraints. Adequate but not thorough.
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?
Extremely concise with two sentences, no fluff. The action is front-loaded in the first sentence. Every word adds value.
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?
For a tool with no output schema and minimal parameter descriptions, the description is incomplete. It lacks parameter details, usage context, and return value information, leaving the agent without enough information to invoke correctly.
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 the parameters 'instance_id' or 'db_path' at all. Users must infer their purpose from context, 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?
The description clearly states the tool reverses a confirmation, returning the obligation instance to 'expected' and clearing matched-transaction evidence. The verb 'Reverse a confirmation' and resource 'reconciliation match' are specific, distinguishing it from sibling 'confirm_reconciliation_match'.
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 explicit guidance on when to use this tool versus alternatives. It implies use after a confirmation, but does not mention prerequisites, exclusions, or when not to use. Lacks 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.
verify_groundingA
Check that every headline dollar figure in a finance payload (a get_finance_status or get_daily_digest result) traces to a source: working cash to the latest operating-account balance snapshot, each upcoming obligation to its instance row, each projection endpoint recomputable from those. Returns a grounding report flagging any number it could not trace. Read-only - use it to verify a finance answer before relying on it.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | ||
| as_of_date | No | ||
| db_path | No |
TDQS
A3.9/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it returns a grounding report flagging untraceable numbers and declares the tool is read-only. Since no annotations are provided, the description carries the full burden and does so well, though it could mention error handling or performance implications.
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 concise, front-loading the main purpose and providing necessary context in a single paragraph. It is efficient but could be slightly better structured with separate parameter explanations.
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?
The description covers the core functionality well, but lacks details on optional parameters and output format. Given the absence of an output schema and the tool's complexity, more information would be beneficial.
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 description explains that the 'payload' should be a result from get_finance_status or get_daily_digest, adding meaning beyond the schema. However, the optional parameters 'as_of_date' and 'db_path' are not mentioned at all, leaving two of three parameters undocumented.
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 verifies that headline dollar figures in a finance payload trace to their sources. It specifically references sibling tools like get_finance_status and get_daily_digest, making it distinct from the many other tools in the list.
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 advises using this tool to verify a finance answer before relying on it, and explicitly notes it is read-only. It provides a clear use case but does not discuss when not to use it or offer alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
write_finance_memoryA
Store a finance memory (a correction, decision, or fact to recall later).
Idempotent by (kind, source, text). Use kind to scope memories, e.g. 'decision', 'correction', 'fact'.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| metadata | No | ||
| kind | No | note | |
| source | No | ||
| db_path | No |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description must disclose behavioral traits. It states idempotency by (kind, source, text), which is key. However, it does not mention other behaviors like persistence guarantees or error handling.
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: first states purpose, second adds critical details (idempotency, kind usage). No unnecessary words, front-loaded.
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 5 parameters with 0% schema coverage, no output schema, and no annotations, the description is incomplete. It explains kind but omits metadata, source, db_path, and return value behavior. Could be more informative.
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 has 0% coverage. Description explains 'kind' with examples and mentions idempotency key involving text and source, but does not explain 'metadata', 'db_path', or the full semantics of 'text' and 'source'. Insufficient compensation.
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 it stores a finance memory (correction, decision, fact) with verb 'Store'. It distinguishes from sibling tools like delete_finance_memory, list_finance_memories, and search_finance_memory.
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?
Explicitly mentions using 'kind' to scope memories and provides examples. Idempotency information guides safe use. Does not explicitly state when not to use, but sibling differentiation is clear.
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.
55 tool updates
v0.1.0- First observed
aggregate_statement_inputs - First observed
apply_charge_onboarding_candidate - First observed
apply_guardrail_rules - First observed
apply_income_source - First observed
apply_obligation_instances - First observed
apply_obligation_migration - First observed
auto_model_high_confidence_recurring - First observed
backfill_recurring_instances - First observed
compare_to_legacy - First observed
confirm_reconciliation_match - First observed
dedupe_todoist_recurring_duplicates - First observed
delete_finance_memory - First observed
detect_drift - First observed
enqueue_todoist_review_batch - First observed
evaluate_guardrails - First observed
execute_action_outbox - First observed
generate_income_instances - First observed
get_background_run - First observed
get_daily_digest - First observed
get_finance_status - First observed
get_next_charge_onboarding_candidate - First observed
import_calendar_facts - First observed
import_todoist_obligations - First observed
list_action_outbox - First observed
list_background_runs - First observed
list_calendar_facts - First observed
list_charge_onboarding_queue - First observed
list_drift_findings - First observed
list_finance_memories - First observed
list_guardrail_findings - First observed
list_income_sources - First observed
list_matched_obligation_instances - First observed
list_obligation_review_candidates - First observed
list_obligations - First observed
list_reconciliation_review_items - First observed
list_statement_cycles - First observed
list_statement_input_estimates - First observed
list_todoist_sync_records - First observed
list_unmatched_obligation_instances - First observed
preview_charge_onboarding_apply - First observed
preview_todoist_review_batch - First observed
recompute_statement_estimates - First observed
reconcile_obligation_instances - First observed
record_charge_onboarding_decision - First observed
resolve_todoist_dedup_conflict - First observed
run_background_sync - First observed
run_live_validation - First observed
scan_charge_onboarding_candidates - First observed
search_finance_memory - First observed
summarize_spending - First observed
sync_simplefin - First observed
sync_todoist - First observed
unconfirm_reconciliation_match - First observed
verify_grounding - First observed
write_finance_memory
TDQS
B3.1/5.0
Scored across 55 tools
Disambiguation4/5
Tools are largely distinct with clear purposes, but the high number (55) may cause some confusion. For example, multiple 'apply_*' and 'list_*' tools are differentiated by their target entities, and detailed descriptions help. A few tools like 'run_background_sync' and 'run_live_validation' have overlapping scopes but are still distinguishable.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern using snake_case (e.g., 'apply_obligation_instances', 'list_drift_findings', 'sync_simplefin'). The pattern is predictable and helps agents infer functionality. No mixed styles or vague verbs are present.
Tool Count2/5
With 55 tools, the server is significantly over the typical well-scoped range (3-15). While each tool addresses a specific need in finance management, this large surface area can overwhelm agents and increase selection errors. The domain could likely be consolidated without losing coverage.
Completeness4/5
The tool set covers a broad lifecycle for obligations, income, reconciliation, drift detection, guardrails, and syncing. Key operations like creation, reading, updating, and deletion are present for most entities, though some CRUD gaps exist (e.g., no explicit delete for obligations). The inclusion of 'verify_grounding' shows attention to integrity.
Related MCP Connectors
Personal-finance workspace for AI agents: accounts, spending, budgets, goals, and investments.
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
- financeOAuthcom.zoninga
Personal finance for AI agents: accounts, budgets, goals, 9-strategy debt payoff, reports. OAuth 2.1
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceTurns a personal-finance SQLite database into typed, schema-validated tools that an AI assistant can call directly, letting you manage accounts, transactions, budgets, debts, investments, tax estimates, and goals through natural language.24 npmMIT
- AlicenseNot gradedqualityCmaintenanceProvides tools for querying and writing finance records in a Notion-backed household finance workspace, enabling management of budgets, expenses, savings, and debt through natural language.MIT
- AlicenseBqualityCmaintenanceEnables an agent to query local financial ledgers for expenses, investments, and income, with tools for savings rate, accounts, sync, and reconciliation.18MIT