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., "@expense-tracker-mcp log 1200 for coffee at Espresso Lab"
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.
A single-user, PKR-only personal expense tracker exposed over MCP, so an agent is the primary interface. Log spending in one sentence — "4500 groceries at Imtiaz" — and ask for totals in another.
Storage is SQLite, embedded in the server process. There is no separate database container to run.
Amounts are integer paisa in storage; rupees are only used at the tool boundary.
Only amount is required to log an expense. The date defaults to today, and the
category is inferred from previous expenses at the same merchant.
Categories are a fixed list (list_categories) so spelling can't fragment your
reports.
Deletes are soft — undo_last() restores.
Duplicates warn, they don't block. An identical amount/merchant/date returns a
possible_duplicate id and saves anyway.
Recurring expenses post themselves on the first tool call after their day passes,
tagged recurring. Nothing is scheduled and nothing double-posts.
Payday is the 1st, so every reporting period is a plain calendar month.
Related MCP server: expense-mcp
The server speaks streamable HTTP at /mcp. It runs as a long-lived container,
not one spawned per session.
docker compose up -d --buildThat publishes http://127.0.0.1:8000/mcp and restarts with Docker.
docker compose logs -f # follow
docker compose down # stop{
"mcpServers": {
"expense-tracker": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}The endpoint has no authentication — anything that can reach the port can read and edit the ledger. Two things keep that contained, and both matter:
Compose publishes on 127.0.0.1 only, so the port is not on your network. Don't
change that to 0.0.0.0 without putting auth in front of it.
DNS-rebinding protection is on, so a browser page can't quietly drive the server.
If you publish on a host port other than 8000, requests fail with HTTP 421 Misdirected Request — the Host header no longer matches the allowlist. Set
EXPENSE_TRACKER_ALLOWED_HOSTS to match, e.g. localhost:9000,127.0.0.1:9000.
Still supported, for debugging or a per-session launch:
docker run -i --rm -e EXPENSE_TRACKER_TRANSPORT=stdio \
-v "$PWD/data:/data" -v "$PWD/backups:/backups" expense-tracker:latest-i is required and -t must not be passed — under stdio a TTY corrupts the
JSON-RPC framing.
Host | Container | Contents |
|
| live |
|
| daily |
Both are gitignored. A snapshot is taken on the first tool call of each day, and
backup_now() forces one.
Both directories live inside this project, so deleting it deletes the history and
the backups. If this data comes to matter, sync ./backups somewhere off-machine.
If SQLite locking misbehaves over the Docker Desktop bind mount, set
EXPENSE_TRACKER_JOURNAL=DELETE.
Variable | Default (container) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
TZ matters: on UTC the container dates anything logged after 7pm PKT to the previous
day, skewing daily totals and month boundaries.
Write — add_expense, add_expenses, update_expense, update_last,
delete_expense, undo_last
Read — list_categories, query_expenses, summarize, search_expenses
Budgets & recurring — set_budget, budget_status, add_recurring,
list_recurring, delete_recurring
Maintenance — backup_now
query_expenses defaults to the current month and caps at 50 rows. For totals, use
summarize — it aggregates in SQL rather than returning rows to be added up.
uv sync --group dev && uv run pytestRun the server outside Docker with uv run expense-tracker — HTTP on
127.0.0.1:8000, against ./data/expenses.db.
The suite covers both transports: a real MCP client over HTTP against a booted server,
and a stdio startup that must leave stdout completely empty (under stdio, stdout
carries the protocol, so a stray print() corrupts it — log to stderr only).
Log an expense in PKR. Only amount is required.
date accepts YYYY-MM-DD, 'today', 'yesterday', '-3d', or a day number; it
defaults to today. When category is omitted it is inferred from previous
expenses at the same merchant. The returned record reflects what was actually
saved, including anything inferred.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| note | No | ||
| tags | No | ||
| amount | Yes | ||
| category | No | ||
| merchant | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains that `date` defaults to today, that omitted `category` may be inferred from previous expenses at the same merchant, and that the returned record reflects exactly what was saved. This gives an agent a realistic picture of side effects and return-value behavior. It does not mention permissions or reversibility, but those are less critical for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: one sentence establishes the core action, a second explains date handling, and a third covers inference and return semantics. There is no filler, no repetition of schema metadata, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter create tool with no annotations and zero schema descriptions, this description covers the essential operating details: currency, required field, date grammar, category inference, and the fact that the returned record reflects saved values. The optional `note` and `tags` are not explained, but they are low-risk and inferable. An agent has enough information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero property descriptions, so the description must supply parameter meaning. It does this well for the key parameters: `amount` is required, `date` has concrete accepted formats and a default, and `category` has an explicit inference rule. `merchant` is mentioned indirectly as the basis for category inference. `note` and `tags` are left undescribed, but they are optional and their names/schema types make them reasonably self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Log an expense in PKR.' It clearly communicates this is a single-expense creation operation and adds useful scope (currency, required amount). It does not explicitly differentiate from the sibling `add_expenses`, relying on singular/plural inference, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives like `add_expenses`, `update_expense`, or `delete_expense`. The description explains parameter behavior (date default, category inference) but never addresses tool selection context or exclusions, leaving the agent to infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log several expenses at once. Each item takes the same fields as add_expense.
Items are validated individually: a bad entry is reported in errors while the
rest still save.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It discloses a key runtime behavior: items are validated individually, bad entries are reported in `errors`, and valid entries still save. This partial-failure behavior is valuable beyond what the schema or tool name implies. It does not mention obvious write side effects, but 'Log' sufficiently implies mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler. The first sentence front-loads the core purpose, and the second adds the important partial-validation behavior. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple batch-wrapper tool, the description covers purpose, item schema source, and failure behavior. Output schema existence covers return shape. The main missing pieces are explicit routing to add_expense for single expenses and any batch-size constraints, but these are minor given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the only parameter `items` is an untyped object array with additionalProperties allowed. The description compensates by stating that each item takes the same fields as add_expense, which is the critical semantic information the schema lacks. It does not enumerate those fields, but it directs the agent to the right source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'Log several expenses at once.' It distinguishes itself from the singular sibling add_expense by emphasizing batch behavior, while also noting that item fields match add_expense. This makes the tool's identity and scope immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Log several expenses at once' implies that this tool is for batch entry, and referencing add_expense suggests the singular alternative. However, the description never explicitly states when to prefer this tool over add_expense or update_expense, nor does it provide when-not/exclusion guidance. Usage expectations are inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a monthly recurring expense (rent, internet, subscriptions).
It posts itself on day_of_month each month, tagged 'recurring'. A day past the
end of a short month posts on that month's last day. If the day has already
passed this month, it posts immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | ||
| category | No | ||
| merchant | No | ||
| day_of_month | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it explains that the expense posts on day_of_month, is tagged 'recurring', handles short months by using the last day, and posts immediately when the day has passed. It does not clarify whether immediate posting also still schedules future recurrences, which is a minor ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The first sentence states the core purpose; the following sentences add only high-value behavioral details. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, recurrence behavior, tagging, and edge cases. An output schema exists, so return values do not need to be described. It could be more complete by naming the one-time alternative explicitly, but the essential invocation context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% parameter description coverage, so the description must compensate. It adds meaningful semantics for day_of_month with scheduling edge cases, but amount, category, and merchant are only addressed by their self-explanatory names. No constraints, units, or formatting are provided for those parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with a specific verb and resource: "Add a monthly recurring expense," with clarifying examples (rent, internet, subscriptions). This clearly separates it from one-time expense tools like add_expense and add_expenses in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: this is for monthly recurring expenses. However, there is no explicit statement of when not to use it or which sibling should be chosen instead, such as add_expense for one-time costs. The guidance is useful but left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a consistent snapshot of the database to the backups directory.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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. 'Consistent snapshot' hints at transaction-level integrity, but the description does not state whether the operation is safe to run concurrently, whether it overwrites existing backups, what filesystem or permission requirements exist, or if it has performance side effects. A 'write' operation is disclosed, but many behavioral aspects remain opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant wording. It conveys the action, the object, and the destination efficiently, earning its place without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter tool with an output schema present, the description is largely adequate. It conveys the purpose and destination without needing to explain return values. However, it omits operational caveats like whether the database must be online or whether existing backups are preserved, which would make the context more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter ambiguity to clarify. The schema already covers everything needed, and the description adds no syntactic detail because none is required. Baseline of 4 for a zero-parameter tool is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Write') and resource ('consistent snapshot of the database to the backups directory'), clearly stating the action and destination. It distinguishes the tool from all siblings, none of which perform backup or snapshot operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit statement of when to invoke this tool or conditions that should trigger a backup, such as before destructive operations or as a periodic safety measure. The absence of any alternative backup-related sibling makes the intended use somewhat implied, but the description does not provide guidance on prerequisites, exclusions, or sequencing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Budget vs. actual for a month ('YYYY-MM', default current), with burn pace.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It usefully discloses the default month behavior and the inclusion of burn pace, which goes beyond the schema. However, it does not explicitly state that this is a read-only operation or describe behavior when no budget is set, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. The core purpose is front-loaded, and the month format/default and burn-pace detail are presented efficiently. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-style tool with an output schema, the description is nearly complete: it explains the input format, default behavior, and what the result covers. It does not explain what 'burn pace' entails or explicitly state that budget is required, but these are not necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates for the single parameter. It specifies the exact 'YYYY-MM' format and clarifies that omitting the month defaults to the current month, which the schema's null default does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a budget-vs-actual comparison for a specific month, which clearly conveys the tool's purpose and scope. It includes the month format and burn-pace output, but lacks an explicit action verb and does not explicitly distinguish itself from siblings like summarize or query_expenses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context—use it for a monthly budget comparison with burn pace—but it does not state when to prefer this tool over alternatives such as summarize, set_budget, or query_expenses. There are no explicit exclusions or sibling routing cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an expense. Soft delete — undo_last() restores it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It clearly discloses that the delete is a soft delete and that undo_last() will restore the expense, which is valuable non-obvious behavior. It does not describe other effects like permissions or error conditions, but for this simple operation the key behavior is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with the primary action first and no filler. The second sentence adds critical behavioral information, so every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema, the description provides the essential behavioral nuance (soft delete) and recovery path. It lacks sibling differentiation from delete_recurring and does not mention edge cases, but these are minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' has no schema description (0% coverage). The description's phrase 'Delete an expense' implies that 'id' identifies which expense to delete, adding some meaning, but it offers no additional detail about how to obtain the id or any constraints beyond the schema's integer type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource, 'Delete an expense', which clearly identifies the operation. It does not explicitly distinguish from sibling tools like delete_recurring, but the resource (expense) is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case for this tool is implied by the description: use it to delete an expense. However, it does not provide explicit guidance on when to use this tool rather than alternatives such as delete_recurring, or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a recurring expense. Already-posted expenses are left in place.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It discloses the key side effect that already-posted expenses are not removed, but it does not clarify whether the recurring rule is deleted or merely disabled, nor does it mention reversibility or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the action front-loaded and the most important caveat immediately after. Every sentence earns its place, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-integer-parameter tool with an output schema present, the description is largely complete: it states the action and the key behavioral boundary. The only real gap is explicit id phrasing, but the context strongly implies the id is the recurring expense id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required integer id with 0% description coverage, and the tool description never mentions the id parameter. An agent can infer that id identifies the recurring expense, but the description adds no explicit parameter-level meaning to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Stop') and a specific resource ('a recurring expense'), and the second sentence clarifies scope by saying posted expenses are left in place. This clearly distinguishes the tool from siblings like delete_expense, which would be used for existing posted expenses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence implies the intended scope: this stops future recurring behavior without touching already-posted expenses. However, it does not explicitly say when to choose this over delete_expense or another alternative, so usage guidance remains mostly inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The valid category names. Expenses must use one of these.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Valid category names' implies a read-only return of allowed values, and the one-sentence description is accurate but sparse; it doesn't mention ordering, completeness, or whether any additional context like locale affects the result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core output ('valid category names') and immediately followed by the use case. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is complete: it states what will be returned and why it matters. An agent has enough information to call it correctly and use the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so param semantics are not needed; the baseline for zero-param tools is 4. The description adds the semantic context that these categories are the allowed set for expenses.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the tool's resource (valid category names) and its role as a constraint for expenses. It lacks an explicit verb like 'list' or 'get,' but the tool name and phrasing make the purpose clear. It doesn't explicitly differentiate from siblings, though none of the siblings overlaps with category listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The statement 'Expenses must use one of these' clearly tells an agent to call this tool when an expense needs a valid category. It provides context for when this tool is relevant, though it doesn't explicitly name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All active recurring expenses.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does add one meaningful behavioral fact—only active recurring expenses are returned—but it does not state whether the operation is read-only, how results are ordered, or whether pagination applies. This is adequate for a simple list tool but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
At six words, the description is extremely concise and contains no filler. It is a sentence fragment and slightly under-specified, but the brevity is appropriate for a zero-parameter list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list operation with an output schema present, the description provides the key context: the resource is recurring expenses and the scope is active ones. It could name alternatives or clarify ordering, but the output schema covers the return contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the input schema leaves nothing for the description to explain. The baseline for parameterless tools applies here, making the description sufficient on this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as recurring expenses and narrows the scope to active ones, which helps distinguish it from one-off expense tools like query_expenses and add_expense. It lacks an explicit verb such as 'returns' or 'lists', but the tool name supplies the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is only implied: call this when active recurring expenses are needed. There is no explicit guidance about when to prefer this over query_expenses, search_expenses, add_recurring, or delete_recurring, and no when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List individual expenses. Defaults to the current month.
For totals use summarize() instead — it is far cheaper than adding up rows here.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| limit | No | ||
| to_date | No | ||
| category | No | ||
| merchant | No | ||
| from_date | No | ||
| max_amount | No | ||
| min_amount | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It does reveal default month behavior and performance/cost characteristics. However, it omits other behavioral traits such as the default limit of 50, ordering, or how filters combine, which are not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero filler. The core purpose is front-loaded, and the alternative-tool guidance is concise and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema reduces the need to explain return values, and the description covers the primary use case and cost guidance. Nevertheless, for an 8-parameter tool with no annotations, it lacks guidance on filter semantics and the relationship to search_expenses, making it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only adds meaning for date parameters via 'Defaults to the current month.' The other seven parameters (tags, limit, category, merchant, max/min_amount) receive no additional semantics beyond their names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'individual expenses', immediately distinguishing it from aggregation tools like summarize. 'Defaults to the current month' further clarifies the exact scope of the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names summarize() as the alternative when totals are needed, and gives a cost rationale ('far cheaper'). It also implies default date behavior, which signals a common use case. However, it does not contrast with search_expenses, leaving some ambiguity between list and search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free-text search across merchant and note, over all time.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the only behavioral signal. It does add useful context: search is free-text, matches merchant and note, and spans all time. But it does not disclose matching semantics like case sensitivity, partial matching, result ordering, or whether limit controls result truncation. Still, nothing about the behavior is hidden in a misleading way.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that packs the essential information with no filler. The verb, resource, matching fields, and temporal scope are all front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter search tool with an output schema, the description covers the core behavior well. But the presence of query_expenses among siblings creates ambiguity that the description does not resolve, and the limit parameter's effect is not clarified. These are real but not severe gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema names parameters but provides no descriptions, and schema coverage is 0%. The description adds meaning to the text parameter by specifying that it searches 'merchant and note'. However, limit is left undocumented, so the description only partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('search'), a specific resource ('expenses'), the fields searched ('merchant and note'), and the time scope ('over all time'). This clearly distinguishes it from siblings like add_expense or summarize, and the free-text qualifier helps differentiate it from query_expenses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when it is appropriate to use: when a free-text search across merchant and note is needed. However, it does not explicitly compare with query_expenses or state when one should be preferred over the other, leaving that routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a monthly spending limit in PKR for a category.
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | ||
| monthly_limit | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full behavioral disclosure burden. It only states the basic action and does not explain whether an existing budget is overwritten, whether the limit must be positive, whether the operation is idempotent, or what side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the core meaning, and it is appropriately sized for a simple two-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the input schema is minimal (0% coverage, no enums) and no annotations are present, the description is too thin to fully support an agent. It lacks behavioral details, parameter constraints, and any guidance on existing budgets, making it incomplete for a mutating tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds the currency context 'PKR' and the notion of a monthly limit, but it does not explain valid category values, restrictions on monthly_limit, or the relationship between the two parameters beyond their obvious titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and resource ('monthly spending limit') with a clear currency and context ('PKR', 'for a category'). It clearly distinguishes itself from sibling tools like budget_status, which would check the budget rather than set it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives such as budget_status or update_expense. The usage is only implied by the verb 'Set' and the resource, but there are no stated conditions, exclusions, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spending totals, pre-computed. Never sum expenses by hand — call this.
group_by is one of category, merchant, month, day, tag.
period is one of this_month, last_month, ytd, all; from_date/to_date override it.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | this_month | |
| to_date | No | ||
| group_by | No | category | |
| from_date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that the tool returns pre-computed totals rather than raw transactions, clarifies that group_by controls the aggregation dimension, and explains that from_date/to_date override period. This is meaningful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences deliver the core purpose and parameter guidance with zero filler. The most important directive is front-loaded, and the parameter constraints are clearly separated into readable lines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return-value documentation is not required. The description covers the key behavioral and parameter context needed to invoke it correctly. Minor gaps like date formatting and explicit alternatives are acceptable but keep it from a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It enumerates the valid values for group_by and period and explains the override relationship with from_date/to_date. It does not specify the expected date format, but the essential parameter semantics are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning spending totals that are pre-computed, with a strong directive to use it instead of manually summing expenses. It is distinct from the sibling query/search tools, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit usage rule: 'Never sum expenses by hand — call this.' This tells the agent when to reach for it, though it does not explicitly describe when to prefer query_expenses or search_expenses instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore the most recently deleted expense.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but does not clarify behavior around edge cases such as no previously deleted expense, whether repeated calls undo multiple deletions, or whether restoring changes expense IDs or dates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. The core action and target are front-loaded and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and an output schema exists, so return values need not be described. Still, with no annotations and no usage or limitation notes, the description is minimally adequate rather than fully complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema description coverage is 100%, so there is nothing for the description to add about parameter syntax or meaning. The baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Restore') and resource ('the most recently deleted expense'), making the tool's core purpose clear. It is semantically distinguishable from siblings like delete_expense and update_last, though it does not explicitly name alternatives or contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'most recently deleted expense' implies when this tool should be used: after deleting an expense by mistake. However, it gives no explicit guidance on when not to use it or which sibling tools to choose for related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an expense. Omitted fields are left alone; pass "" to clear a text field.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| date | No | ||
| note | No | ||
| tags | No | ||
| amount | No | ||
| category | No | ||
| merchant | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does disclose the two most important behavioral traits: partial-update merge semantics ('Omitted fields are left alone') and the empty-string clearing rule for text fields. However, it is silent on how null values behave across all nullable parameters, whether an edit is reversible via undo_last, and what happens when an invalid id is supplied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 17-word sentence that front-loads the action ('Edit an expense') and then packs both essential behavioral rules with zero filler or redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation is not needed, but for a 7-parameter partial-update tool with no annotations and 0% schema coverage, the description leaves notable gaps: null-handling semantics, behavior on an invalid id, and how this tool relates to update_last or undo_last for recovery. It covers the core merge behavior but not enough for an agent to invoke it confidently in all cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds genuine meaning beyond the schema's bare types and defaults: that omitting a parameter leaves it untouched, and that passing an empty string clears a text field. However, it leaves non-text fields (amount, tags) ambiguous, and the schema's default of null for every optional parameter creates confusion about whether explicitly passing null clears a field or leaves it alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource, 'Edit an expense,' which clearly communicates a targeted mutation of one existing record. It is easily distinguished from add_expense/add_expenses (creation) and delete_expense (removal), though it does not explicitly differentiate itself from update_last, a sibling that also edits an existing expense.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to select this tool over its alternatives. There is no mention of update_last (for editing the most recently added expense), add_expense, or delete_expense, and no exclusions or conditions are stated. The omission semantics ('Omitted fields are left alone') describe how to invoke parameters, not when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Correct the most recently logged expense without needing its id.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| note | No | ||
| tags | No | ||
| amount | No | ||
| category | No | ||
| merchant | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It indicates a mutation operation but does not describe whether it performs a partial update or full overwrite, what happens if no expense exists, or whether the change is reversible. This is a significant gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tight sentence that front-loads the primary action and the key constraint. Every word earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter mutation tool with no annotations and no schema descriptions, the description leaves critical unknowns: whether calling with no arguments is valid, which fields can be corrected, and how 'most recently logged' is determined. The output schema helps with return values but does not compensate for missing usage semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description names no parameters, so it adds no meaning beyond the field names and types. The parameter names are somewhat self-explanatory, but the description does not clarify update semantics or how the optional, nullable parameters behave individually.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Correct'), a precise resource ('the most recently logged expense'), and a distinguishing constraint ('without needing its id'). This clearly differentiates it from update_expense and is not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without needing its id' implicitly contrasts with update_expense, giving clear context for when this tool is appropriate. However, it does not explicitly name alternatives or state exclusions, such as when to prefer undo_last or update_expense instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_expenseadd_expensesadd_recurringbackup_nowbudget_statusdelete_expensedelete_recurringlist_categorieslist_recurringquery_expensessearch_expensesset_budgetsummarizeundo_lastupdate_expenseupdate_lastScored across 16 tools
Most tools have clearly distinct roles: adding, editing, deleting, querying, summarizing, budgeting, and recurring expenses. Some pairs like add_expense/add_expenses and query_expenses/search_expenses could be confused, but the descriptions clarify the intended use.
The majority of tools follow a consistent snake_case verb_noun pattern like add_expense, list_recurring, and delete_expense. A few outliers such as summarize, budget_status, undo_last, and update_last break the pattern slightly, but the overall style is predictable.
At 16 tools, the set is slightly above the ideal 3-15 range but still well-scoped for an expense tracker. Each tool covers a meaningful part of the domain without obvious redundancy.
The tool surface covers the full expense lifecycle: single and bulk creation, updates, deletion, undo, querying, searching, summarizing, budgets, recurring expenses, and backup. Supporting workflows like recurring and budget management have matching setup, status, and teardown tools.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
Corporate travel booking and expense management for TripGain, exposed as an MCP server.
Hosted MCP server for Mini Accountant: invoices, expenses, customers, analytics, tax estimates.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
