ZenMoney MCP Server

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 by disclosing the two-phase dry-run workflow, the default preview mode, the need for explicit confirmation, and that tagId null clears the category. It does not cover permissions, reversibility, or error behavior, but the critical mutation safety behavior is clear.

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 three short sentences and front-loads the core write behavior and safety protocol. Every sentence adds actionable information with no waste.

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

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

For a mutation tool with no annotations and no output schema, the description provides enough behavioral context to call it safely: dry-run first, show preview, confirm, then write. It could be more complete about response format or failure modes, but the essential safety contract 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?

Schema coverage is 50%, with dryRun already documented in the schema. The description adds useful meaning for dryRun's workflow role and for tagId null clearing the category, but it does not explain the changes array structure or transactionId semantics.

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: writing category changes back to ZenMoney. It is clearly a mutation tool and distinct from likely read-oriented siblings such as zen_review_expenses and zen_find_transactions, though it does not explicitly name those alternatives.

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 workflow: always call with dryRun:true first, present the preview, and only call with dryRun:false after explicit user confirmation. It does not contrast with sibling tools, but the procedural guidance is clear and strong.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It does add one genuine behavioral fact — results are returned newest-first — but says nothing about the default result count, whether the 1–500 limit is paginated, what authentication/scope applies, or what the response contains. For a 10-parameter query tool with zero annotation coverage this is thin.

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

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

A single front-loaded sentence names the operation and ordering, then a second sentence enumerates filters. No filler, no redundancy, and the most important scoping facts come first.

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

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

With no output schema, no annotations, and 10 parameters at 0% coverage, the description should tell the agent more — notably the date string format, what minOutcome/limit mean, and whether results are truncated. It is adequate to start an invocation but not sufficient to call confidently without guessing.

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 — and it does map 8 of 10 parameters to meaning: 'date range' clarifies from/to as dates, 'merchant/payee/mcc' disambiguates three similar string/number fields, and the two '*-only' booleans are explained by name. It leaves 'limit' (bounds are in schema but no default/reset behavior) and 'minOutcome' entirely unexplained, which is the gap keeping this below 5.

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?

States a specific verb+resource ('filtered transaction lookup') plus the ordered semantics ('newest first'), and enumerates the filter axes, so an agent can tell this is a read/find tool. It does not, however, distinguish itself from siblings like zen_review_expenses or zen_merchant_history, which overlap on transaction retrieval.

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

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

The filter list implies when the tool is useful ('uncategorized-only', 'needs-review-only' hint at review workflows) but never states when to prefer it over zen_review_expenses or zen_merchant_history, nor any exclusions or prerequisites. Usage must be inferred from the parameter names.

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

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

With no annotations, the description carries the burden and does well: it discloses dedup by date + amount, that credit repayments/transfers are never created, and that new transactions land without a category. It omits permissions/auth requirements, whether re-running is idempotent beyond dedup, and failure modes for malformed PDFs.

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?

Four sentences, no filler, front-loaded with purpose then the mandatory safety workflow then the follow-up tool. Every sentence carries actionable information.

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

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

A mutation tool with no annotations and no output schema, yet the purpose, the safety protocol, the dedup semantics, and the follow-up step are all covered. The only gap is what the dry-run plan output actually looks like, which would help the agent present it to the user.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: dryRun defaults to true and must be sequenced deliberately, and filePath is constrained to an Ozon-bank PDF. That is more than restating the schema.

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

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

Names a specific verb (import) and resource (transactions from an Ozon-bank PDF statement into a ZenMoney account), plus the exact scope: missing transactions only, deduplicated by date + amount. This clearly separates it from zen_sync (general sync) and zen_find_transactions (read-only lookup).

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?

Prescribes an explicit two-step workflow: dryRun:true first, present the plan to the user, then dryRun:false only after explicit confirmation. It also routes follow-up work to zen_review_expenses for categorization, so the agent knows both when to call this and what to do next.

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

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

With no annotations, the description carries the full disclosure burden; 'vocabulary' and 'list' imply a read-only lookup, and the mention of hierarchy and human-readable paths gives some sense of the returned content. However, it does not state pagination, caching, or whether the result is a flat set or nested tree, leaving meaningful behavioral gaps.

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, and the resource definition is front-loaded before the usage hint. The first sentence is a noun phrase rather than a verb-led statement, which slightly weakens the lead.

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-optional-param read tool with no output schema, the description should at least sketch the return shape; it hints at ids, paths, and hierarchy but does not say whether results is flat or nested or how many are returned. Adequate but not 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?

There is a single optional parameter whose schema description already documents the kind enum and its default of 'outcome'; description coverage is 100%. The description adds no additional meaning about filtering or what 'all' yields, so the baseline 3 applies.

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

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

Identifies the resource precisely: the category (tag) vocabulary, including hierarchy and human-readable paths. It lacks an explicit verb like 'list/retrieve', but the content is concrete enough to separate it from sibling tools such as zen_apply_categories, which mutates rather than reads.

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, 'Use the ids when proposing category changes', implies a workflow link to zen_apply_categories, but it never states when to call this tool versus the alternatives or what preconditions exist. Usage is inferable rather than explicit.

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

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

With no annotations, the description must carry behavior, and it does disclose the shape of the response (frequencies, totals, recent examples), which signals a read-only analytical lookup. It does not state how 'recent examples' is bounded, whether any key is required, or what happens when several keys are 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?

Two sentences, front-loaded with the resource and its lookup keys, then the use case. Dense and largely waste-free, though the parenthetical key list sits awkwardly mid-sentence.

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?

All five params are optional, there is no output schema and no annotations, so the description should explain parameter interplay and defaults. It covers output content and intent but leaves date-range filtering and multi-key precedence unspecified.

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% across 5 params, and the description only accounts for three of them (merchant, payee, mcc). The from/to date-range parameters — potentially the key scoping inputs for a 'historical' tool — are never mentioned, leaving a real gap the schema does not fill.

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?

States a specific resource and scope: historical category breakdown per merchant, with the three lookup keys (merchant id, payee text, mcc) and the returned content (usage frequency, totals, recent examples). It implicitly distinguishes itself from zen_review_expenses via 'when a review row is ambiguous,' though no sibling is named outright.

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?

'Use to dig deeper when a review row is ambiguous' gives a concrete triggering condition that routes the agent away from the review tool. No when-not guidance or explicit named alternative (e.g. zen_find_transactions vs this) is offered.

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

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

With no annotations, the description carries the burden and does well: it discloses the return contents (current category, ranked candidates with confidence, inferred from history at the same place) and implicitly establishes that this tool is read-only — decisions and writes happen elsewhere. It is silent on ordering, truncation at the 300 limit, and any cost/latency of the history inference.

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?

Three sentences, front-loaded with purpose, then output semantics, then the required next step. No filler and no repetition of schema fields.

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

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

No output schema exists, and the description compensates by describing the returned shape and its meaning in enough detail to act on. The remaining gap is behavioral detail around limit/truncation and result ordering for a 5-parameter 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 coverage is 80%, so the baseline is 3; from/to are documented in the schema. The description only implicitly touches includeOk by framing the default as uncategorized/mis-categorized items, and says nothing about how limit or account interact with the audit output.

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?

States a specific verb and resource ('Audit expenses in a date range') and immediately defines the result set: uncategorized or likely mis-categorized items. This distinguishes it cleanly from siblings like zen_find_transactions (search) and zen_merchant_history (lookup history at one merchant).

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

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

Explicitly routes the agent: it decides the final category itself and then proposes changes via zen_apply_categories, and should run zen_sync first if the cache may be stale. Both the next step and the prerequisite are named, so the workflow is unambiguous.

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

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

With no annotations, the description carries the full burden: it discloses that this writes to a local cache and that full:true re-fetches history, implying a heavier operation. It does not say whether local data is replaced or lost, how long a full sync takes, or whether concurrent reads are affected — meaningful gaps for an unannotated mutating tool.

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?

Three short sentences, front-loaded with the action, then timing, then the parameter caveat. Nothing is redundant.

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-optional-param tool with no output schema, the essentials — what it does, when to run it, and what the flag changes — are all present. Only the side effects on existing cached data are left unstated.

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

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

Schema coverage is 100% and the single param is already described as "Re-fetch everything from scratch." The description's "full:true re-fetches the entire history" adds no meaning beyond that wording, so baseline 3 applies.

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

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

States a specific verb and resource: pulling ZenMoney data into the local cache. This clearly separates it from the sibling tools, which are query/analysis operations rather than a cache-priming sync, though it never names an alternative explicitly.

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?

"Run this before auditing if the data may be stale" gives a concrete trigger condition tied to downstream work. It offers clear context but no explicit when-not-to-use guidance or named alternatives.

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