Skip to main content
Glama

create_transaction

Create a new transaction (income, expense, or transfer). Requires accountId, amount (decimal), transactionType, and transferNature. paymentType is optional and defaults to the default payment type of the account. For transfers, also provide destinationAccountId and destinationAmount. Use splits to categorize portions of the amount. Use originalAmount + originalCurrencyCode to record what the purchase cost in its invoice currency when that differs from the account currency. Use paymentLegs to pay one purchase from several accounts. Use payeeId to link an existing payee, or merchantName to let the server resolve a payee from a raw merchant name (it matches an existing payee by name or alias and follows the instance's normal promotion rules, so it may not create a payee on first sight); the two cannot be combined. Requires finance:write scope.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "accountId": "<accountId>",
      "amount": "<amount>",
      "transactionType": "<transactionType>",
      "transferNature": "<transferNature>"
    },
    "name": "create_transaction"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNoOptional note or description for the transaction
timeNoTransaction date/time as ISO 8601 string. Defaults to now
amountYesTransaction amount as an unsigned decimal (e.g. 12.50). Never negative: transactionType sets the direction
splitsNoSplit the transaction across multiple categories. Each item: { categoryId, amount (decimal, greater than 0), note (optional) }
tagIdsNoTag IDs to assign to this transaction
payeeIdNoID of an existing payee to link (from get_payees). Cannot be combined with merchantName
locationNoWhere it happened: { latitude, longitude } in degrees
accountIdYesID of the account the transaction belongs to
isPlannedNoMark the transaction as planned rather than an already-happened record
categoryIdNoCategory ID to assign to this transaction
externalUrlNohttp(s) link to the source document, e.g. an invoice (max 2048 characters)
payeeLockedNotrue pins the payee so later automations and bank sync never change it
paymentLegsNoPay this income/expense from up to 4 more accounts. Each item is either { accountId, amount } to create a part on another account, or { transactionId } to link an existing transaction as a part (its amount stays). amount is in that account's currency; when it differs from this transaction's currency also pass paymentAmount, the part's value in this transaction's currency. Not allowed for transfers, refunds, planned or category-split transactions
paymentTypeNoPayment method used. Defaults to the account's default payment type, or bankTransfer
merchantNameNoRaw merchant name, resolved to a payee the way bank sync and imports do: an existing payee is matched by name or alias, and a new one is created only once the name has repeated enough (the instance promotion rule). Cannot be combined with payeeId
originalAmountNoAmount in the currency the purchase was originally priced in (decimal), e.g. 66.42 for a PLN invoice paid from a UAH account. Informational only: never affects balances. Requires originalCurrencyCode
transferNatureYesTransfer type. Use not_transfer for regular income/expense
transactionTypeYesWhether this is income or expense
applyAutomationsNotrue runs the user's enabled automation rules on this transaction. Default false
excludeFromStatsNoKeep the transaction out of every spending/income report. It still counts toward balances and stays in the transaction list
destinationAmountNoFor transfers: amount received in destination account (decimal, greater than 0)
externalReferenceNoExternal reference such as an invoice or order number (max 255 characters)
destinationAccountIdNoFor transfers: destination account ID
originalCurrencyCodeNoISO 4217 code of originalAmount (e.g. "PLN"). Requires originalAmount. Cannot be combined with transfer fields
destinationTransactionIdNoFor transfers: link to an existing destination transaction instead of creating one

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / excludeFromStats
      Added value: +{
      +  "default": false,
      +  "description": "Keep the transaction out of every spending/income report. It still counts toward balances and stays in the transaction list",
      +  "type": "boolean"
      +}
  2. Changed32 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • removedInput schema / properties / accountId / pattern
      Removed value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    • addedInput schema / properties / applyAutomations
      Added value: +{
      +  "default": false,
      +  "description": "true runs the user's enabled automation rules on this transaction. Default false",
      +  "type": "boolean"
      +}
    • removedInput schema / properties / categoryId / pattern
      Removed value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    • removedInput schema / properties / destinationAccountId / pattern
      Removed value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    • removedInput schema / properties / destinationTransactionId / pattern
      Removed value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    • addedInput schema / properties / externalReference
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maxLength": 255,
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "External reference such as an invoice or order number (max 255 characters)"
      +}
    • addedInput schema / properties / externalUrl
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maxLength": 2048,
      +      "pattern": "^https?:\\/\\/",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "http(s) link to the source document, e.g. an invoice (max 2048 characters)"
      +}
    • addedInput schema / properties / isPlanned / default
      Added value: +false
    • addedInput schema / properties / location
      Added value: +{
      +  "anyOf": [
      +    {
      +      "properties": {
      +        "latitude": {
      +          "maximum": 90,
      +          "minimum": -90,
      +          "type": "number"
      +        },
      +        "longitude": {
      +          "maximum": 180,
      +          "minimum": -180,
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "latitude",
      +        "longitude"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Where it happened: { latitude, longitude } in degrees"
      +}
    • addedInput schema / properties / merchantName
      Added value: +{
      +  "description": "Raw merchant name, resolved to a payee the way bank sync and imports do: an existing payee is matched by name or alias, and a new one is created only once the name has repeated enough (the instance promotion rule). Cannot be combined with payeeId",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / note / anyOf
      Added value: +[
      +  {
      +    "maxLength": 1000,
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedInput schema / properties / note / maxLength
      Removed value: -1000
    • removedInput schema / properties / note / type
      Removed value: -"string"
    • addedInput schema / properties / payeeId / anyOf
      Added value: +[
      +  {
      +    "format": "uuid",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / payeeId / description
      Previous value: -"Payee ID to assign"New value: +"ID of an existing payee to link (from get_payees). Cannot be combined with merchantName"
    • removedInput schema / properties / payeeId / format
      Removed value: -"uuid"
    • removedInput schema / properties / payeeId / pattern
      Removed value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    • removedInput schema / properties / payeeId / type
      Removed value: -"string"
    • addedInput schema / properties / payeeLocked
      Added value: +{
      +  "description": "true pins the payee so later automations and bank sync never change it",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / paymentLegs / items / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "amount": {
      -        "exclusiveMinimum": 0,
      -        "type": "number"
      -      },
      -      "paymentAmount": {
      -        "exclusiveMinimum": 0,
      -        "type": "number"
      -      },
      -      "transactionId": {
      -        "format": "uuid",
      -        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "transactionId"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "accountId": {
      -        "format": "uuid",
      -        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      -        "type": "string"
      -      },
      -      "amount": {
      -        "exclusiveMinimum": 0,
      -        "type": "number"
      -      },
      -      "paymentAmount": {
      -        "exclusiveMinimum": 0,
      -        "type": "number"
      -      }
      -    },
      -    "required": [
      -      "accountId",
      -      "amount"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "amount": {
      +        "exclusiveMinimum": 0,
      +        "type": "number"
      +      },
      +      "paymentAmount": {
      +        "exclusiveMinimum": 0,
      +        "type": "number"
      +      },
      +      "transactionId": {
      +        "format": "uuid",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "transactionId"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "accountId": {
      +        "format": "uuid",
      +        "type": "string"
      +      },
      +      "amount": {
      +        "exclusiveMinimum": 0,
      +        "type": "number"
      +      },
      +      "paymentAmount": {
      +        "exclusiveMinimum": 0,
      +        "type": "number"
      +      }
      +    },
      +    "required": [
      +      "accountId",
      +      "amount"
      +    ],
      +    "type": "object"
      +  }
      +]
    • changedInput schema / properties / paymentType / enum
      Previous value: -[
      -  "bankTransfer",
      -  "cash",
      -  "creditCard",
      -  "debitCard",
      -  "mobilePayment",
      -  "voucher",
      -  "webPayment"
      -]New value: +[
      +  "bankTransfer",
      +  "voucher",
      +  "webPayment",
      +  "cash",
      +  "mobilePayment",
      +  "creditCard",
      +  "debitCard"
      +]
    • changedInput schema / properties / splits / description
      Previous value: -"Split the transaction across multiple categories"New value: +"Split the transaction across multiple categories. Each item: { categoryId, amount (decimal, greater than 0), note (optional) }"
    • removedInput schema / properties / splits / items / properties / amount / description
      Removed value: -"Amount for this split portion (decimal, greater than 0)"
    • removedInput schema / properties / splits / items / properties / categoryId / description
      Removed value: -"Category ID for this split portion"
    • removedInput schema / properties / splits / items / properties / categoryId / pattern
      Removed value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    • removedInput schema / properties / splits / items / properties / note / description
      Removed value: -"Optional note for this split"
    • addedInput schema / properties / splits / maxItems
      Added value: +10
    • removedInput schema / properties / tagIds / items / pattern
      Removed value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    • addedInput schema / properties / tagIds / maxItems
      Added value: +20
    • addedInput schema / properties / time / format
      Added value: +"date-time"
    • addedInput schema / properties / time / pattern
      Added value: +"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
  3. Changed3 schema fields changed
    • addedInput schema / properties / paymentLegs
      Added value: +{
      +  "description": "Pay this income/expense from up to 4 more accounts. Each item is either { accountId, amount } to create a part on another account, or { transactionId } to link an existing transaction as a part (its amount stays). amount is in that account's currency; when it differs from this transaction's currency also pass paymentAmount, the part's value in this transaction's currency. Not allowed for transfers, refunds, planned or category-split transactions",
      +  "items": {
      +    "anyOf": [
      +      {
      +        "additionalProperties": false,
      +        "properties": {
      +          "amount": {
      +            "exclusiveMinimum": 0,
      +            "type": "number"
      +          },
      +          "paymentAmount": {
      +            "exclusiveMinimum": 0,
      +            "type": "number"
      +          },
      +          "transactionId": {
      +            "format": "uuid",
      +            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "transactionId"
      +        ],
      +        "type": "object"
      +      },
      +      {
      +        "additionalProperties": false,
      +        "properties": {
      +          "accountId": {
      +            "format": "uuid",
      +            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      +            "type": "string"
      +          },
      +          "amount": {
      +            "exclusiveMinimum": 0,
      +            "type": "number"
      +          },
      +          "paymentAmount": {
      +            "exclusiveMinimum": 0,
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "accountId",
      +          "amount"
      +        ],
      +        "type": "object"
      +      }
      +    ]
      +  },
      +  "maxItems": 4,
      +  "type": "array"
      +}
    • changedInput schema / properties / paymentType / description
      Previous value: -"Payment method used"New value: +"Payment method used. Defaults to the account's default payment type, or bankTransfer"
    • changedInput schema / required
      Previous value: -[
      -  "accountId",
      -  "amount",
      -  "transactionType",
      -  "paymentType",
      -  "transferNature"
      -]New value: +[
      +  "accountId",
      +  "amount",
      +  "transactionType",
      +  "transferNature"
      +]
  4. Changed2 schema fields changed
    • addedInput schema / properties / note / maxLength
      Added value: +1000
    • changedInput schema / properties / splits / items / properties / note / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "maxLength": 100,
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  5. Changed1 schema field changed
    • addedInput schema / properties / payeeId
      Added value: +{
      +  "description": "Payee ID to assign",
      +  "format": "uuid",
      +  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      +  "type": "string"
      +}
  6. Changed6 schema fields changed
    • changedInput schema / properties / amount / description
      Previous value: -"Transaction amount as a decimal (e.g. 12.50)"New value: +"Transaction amount as an unsigned decimal (e.g. 12.50). Never negative: transactionType sets the direction"
    • addedInput schema / properties / amount / minimum
      Added value: +0
    • changedInput schema / properties / destinationAmount / description
      Previous value: -"For transfers: amount received in destination account (decimal)"New value: +"For transfers: amount received in destination account (decimal, greater than 0)"
    • addedInput schema / properties / destinationAmount / exclusiveMinimum
      Added value: +0
    • changedInput schema / properties / splits / items / properties / amount / description
      Previous value: -"Amount for this split portion (decimal)"New value: +"Amount for this split portion (decimal, greater than 0)"
    • addedInput schema / properties / splits / items / properties / amount / exclusiveMinimum
      Added value: +0
  7. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=false; the description carries the rest and does so well: it names the required finance:write scope, warns that merchantName 'may not create a payee on first sight' due to promotion rules, clarifies originalAmount is 'Informational only: never affects balances', and states payeeLocked pins the payee against later automations and bank sync. These are non-obvious side effects an agent could not infer from the write annotation alone.

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?

It is a single dense paragraph but front-loads the required fields and the core verb before the optional features, and each sentence introduces a distinct capability. Some redundancy with the already-complete schema descriptions prevents a top score.

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

Completeness4/5

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

For a 25-parameter creation tool with only a write annotation and no output schema, the description covers the risky interactions (transfer fields, legs, splits, payee resolution, scope) thoroughly. The remaining gap is the response shape — it never says whether the created transaction (or its ID) is returned, which matters for chaining into assign_tags_to_transaction or update_transaction.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns more by explaining cross-parameter semantics the schema states only per-field, notably the payeeId/merchantName mutual exclusion, the originalAmount+originalCurrencyCode pairing, and the destinationAmount requirement for transfers. A few statements merely restate schema text (paymentType default, transfer fields), keeping it below a 5.

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 opening sentence states a specific verb and resource and enumerates the three variants it handles (income, expense, transfer), immediately followed by the four required fields. An agent can tell this is the creation tool and not the update/split/delete siblings without opening the schema.

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?

It gives concrete conditional guidance for optional features ('For transfers, also provide destinationAccountId', 'Use paymentLegs to pay one purchase from several accounts', 'Use originalAmount + originalCurrencyCode ... when that differs from the account currency') plus hard exclusions ('the two cannot be combined', paymentLegs 'Not allowed for transfers, refunds, planned or category-split transactions'). It stops short of routing the agent to a named alternative tool, so no explicit when-not-to-use-this-tool statement exists.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.