gnucash-mcp

by ninetails-io

Overview Schema Source Related Servers Discussions Admin

Python

Local

create_prices

Record many prices in one call using TSV bulk input; existing quotes are updated in place, avoiding duplicates.

Instructions

Record MANY prices in one call (bulk quote entry).

INPUT — prices is a TSV block: a header row, then one row per price. Required columns ref, commodity, date, value; optional columns extend the header IN ORDER: ns, cur, source, type (stop anywhere; rows may end early; empty cells take defaults)::

ref<TAB>commodity<TAB>date<TAB>value<TAB>cur<TAB>source
1<TAB>VTSAX<TAB>2026-07-21<TAB>148.32<TAB><TAB>web:yahoo
2<TAB>EUR<TAB>2026-07-21<TAB>1.0845<TAB><TAB>web:ecb

ref: your correlation key, echoed in results.
ns: commodity namespace; empty auto-resolves when the symbol is unambiguous across namespaces.
cur: quote currency; empty = book default.
source: where the quote came from (provenance — default "user:price"); type: nav/last/bid/ask.

Per-row semantics are create_price's exactly: an existing price with the same commodity/currency/date/source is UPDATED in place (status: updated), never duplicated. One book open, one save, on_error="abort" (default) sinks the whole batch on any bad row; dry_run=true previews as would_create / would_update.

The companion work list: list_commodities(stale_days=30, held_only=true).

Input Schema

TableJSON Schema

Name	Required	Default
`prices`	Yes
`dry_run`	No
`on_error`	No	abort

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.4.2Aug 3, 2026

TDQS

A5/5.0

Behavior5/5

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

The description reveals critical behavior beyond annotations: existing prices with the same commodity/currency/date/source are updated in place with status 'updated', never duplicated; the whole batch is sunk on any bad row under on_error='abort'; and dry_run=true previews as 'would_create'/'would_update'. It also notes one book open and one save, which is not inferable from 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.

Conciseness5/5

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

The description is long only because the TSV format is complex; every block serves a purpose: input grammar, example, per-column semantics, batch behavior, and companion tool. The front-loaded one-line summary makes the core purpose immediately identifiable.

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

Completeness5/5

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

The description is complete for a tool with a complex data input and error semantics. It explains the full input contract, defaults, update-in-place behavior, atomic failure mode, dry-run statuses, and even the companion listing tool, so an agent can invoke it safely and correctly without digging elsewhere.

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

Parameters5/5

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

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It precisely documents the `prices` TSV format with required and optional columns, per-column defaults, and gives a concrete multi-row example. `dry_run` and `on_error` are each given behavioral meaning beyond their schemas.

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?

"Record MANY prices in one call (bulk quote entry)" clearly states the verb, resource, and batch scope, and distinguishes it from the single-item sibling create_price. The opening sentence is 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 Guidelines5/5

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

The description explicitly says per-row semantics match create_price's exactly, signals dry_run and on_error behaviors, and points to list_commodities(stale_days=30, held_only=true) as the companion work list. An agent knows when this tool applies and what alternatives/contexts exist.

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

Deploy Server