Skip to main content
Glama

Taokeh MCP server

Stock movements

stock_movements
Read-only

Read the STOCK MOVEMENT LEDGER in bulk — every recorded change to on-hand quantity, across products, in one call (and every changed cost: a revaluation row has qtyDelta 0 and carries the NEW cost in unitCost — the owner changed the item's average cost and Taokeh booked the difference that day). stock_level says how many you have RIGHT NOW for one product; this says WHAT MOVED, WHEN, WHY and WHAT IT LEFT BEHIND. Use it for stock-turn analysis, shrinkage hunting, reorder timing, or reconstructing how a balance got where it is. Every filter is optional and a bare call is a legitimate "what moved lately" pull: narrow with product (case-insensitive contains against the product name OR SKU), from/to (a window on each row's docDate) and sourceType (exactly one cause — see the list). Each row: ts (when it was posted), docDate (the document's own date, YYYY-MM-DD — a voided or edited bill's reversal keeps the bill's date, while a voided credit or debit note's reversal is dated the day of the void, like its journal entry; where no document survives, the Malaysian day it was posted), product {sku, name}, qtyDelta (signed — negative took stock out), balanceAfter (on-hand immediately after that move, as the posting path recorded it), unitCost, reason (free text the person typed, where there was one), sourceType and sourceId (the id of the document that moved it — pair it with search_documents to see which one), and editReversal: true on a purchase_void / sale_void row written by an EDIT, not a void — never count it as one. When the edit kept the product, its repost is the purchase / sale row at the same ts; when the edit removed it, there is no repost and the quantity really left. ⚠ WHICH MOVEMENTS EXIST AT ALL DEPENDS ON THIS COMPANY'S STOCK MODE, and the answer says which mode it is in (stockMode) with a note. In modified_periodic — the mode of companies created before 28 Sep 2026 unless they switched; newer companies start perpetual — selling does NOT move stock: invoices, delivery orders and credit notes write no movement row, and stock is trued up at stock take. Seeing no 'sale' rows there means the company is periodic; it does NOT mean nothing was sold, and it is NOT shrinkage. Only a perpetual company ORIGINATES sale / credit_note rows — but a periodic company can still HOLD them, and can still gain new ones: rows written while it ran perpetual stay, and a VOID takes its truth from the document's own movement rows rather than from today's setting, so voiding a perpetually-booked invoice or supplier return writes a fresh sale_void / debit_note_void row in a company that is periodic now. So a periodic company with movement rows is not a contradiction and not a bug. Read the mode before you interpret the rows, and read a row's own sourceType before you attribute it to the mode. balanceAfter is the total across the whole company, not per location; on a multi-location company each row also carries location. A stock take of ONE location can write a PAIR of stock_take rows with the same sourceId and opposite qtyDelta — one at the location, one with no location. Its reason is 'Stock take · : ' followed by 'N sold earlier from no shelf', 'N placed from no location', 'N written off from no location', or 'P placed from no location, W written off from no location'. Whatever its words, any such stock_take pair (opposite qtyDelta under one sourceId and product) nets to zero: it corrects where the stock sits on the shelves, not how much there is — the take's other rows carry its real change. Never count the pair as stock coming in or going out; sum qtyDelta per sourceId and product. An adjustment row with no location on a multi-location company can be a write-off of stock that was on record at no location, a move made before the company had locations, or a move at a location that has since been deleted. Rows come back newest first, capped at 200 with total, shown and more — when more is true, narrow by date and pull the periods in turn rather than treating a partial page as the whole. Values are verbatim as recorded at the time, never re-derived. ⛔ WHAT IT WILL NOT DO: it does not value your inventory (balance_sheet does), does not compute COGS or margin (income_statement, profit_drivers), and does not tell you what to reorder (low_stock). Nothing is written, and no draft is created.

Input Schema

NameRequiredDescriptionDefault
toNoLatest docDate (YYYY-MM-DD; the document date, else the Malaysian posting day).
skuNoNOT a filter on this tool. Pass it as `product` — one case-insensitive contains matched against BOTH the product name and the SKU.
dateNoNOT a filter on this tool. Pass a date WINDOW as `from` and/or `to` (YYYY-MM-DD). A single date is `from` and `to` set to the same day.
fromNoEarliest docDate (YYYY-MM-DD; the document date, else the Malaysian posting day). The main way to break a >200-row pull into honest slices.
itemNoNOT a filter on this tool. Pass it as `product` — one case-insensitive contains matched against BOTH the product name and the SKU.
nameNoNOT a filter on this tool. Pass it as `product` — one case-insensitive contains matched against BOTH the product name and the SKU.
typeNoNOT a filter on this tool. Pass the movement cause as `sourceType`.
limitNoNOT a filter on this tool. The page size is fixed at 200 movements. Narrow with from/to, product or sourceType and pull the periods in turn.
queryNoNOT a filter on this tool. Pass it as `product` — one case-insensitive contains matched against BOTH the product name and the SKU.
dateToNoNOT a filter on this tool. Pass the end of the window as `to`.
reasonNoNOT a filter on this tool. `reason` is free text the person typed and is RETURNED on each row, not a filter. To narrow by cause use `sourceType` (e.g. 'adjustment').
sourceNoNOT a filter on this tool. Pass the movement cause as `sourceType`.
productNoCase-insensitive contains matched against the product NAME or SKU. Omit for every product.
dateFromNoNOT a filter on this tool. Pass the start of the window as `from`.
productIdNoNOT a filter on this tool. This search matches product TEXT, not ids — pass the name or SKU as `product`.
sourceTypeNoExactly one movement cause. One of: purchase, purchase_void, debit_note, debit_note_void, adjustment, stock_take, import_opening, assembly_out, assembly_in, disassembly_out, disassembly_in, sale, sale_void, credit_note, transfer_out, transfer_in, revaluation. Note that sale, sale_void, credit_note are only ever CREATED by a perpetual company — a company that has since switched to periodic still holds the ones it wrote (and a void of one of those documents still writes its reversal leg).
productNameNoNOT a filter on this tool. Pass it as `product` — one case-insensitive contains matched against BOTH the product name and the SKU.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / sourceType / description
      Previous value: -"Exactly one movement cause. One of: purchase, purchase_void, debit_note, debit_note_void, adjustment, stock_take, import_opening, assembly_out, assembly_in, disassembly_out, disassembly_in, sale, sale_void, credit_note, transfer_out, transfer_in. Note that sale, sale_void, credit_note are only ever CREATED by a perpetual company — a company that has since switched to periodic still holds the ones it wrote (and a void of one of those documents still writes its reversal leg)."New value: +"Exactly one movement cause. One of: purchase, purchase_void, debit_note, debit_note_void, adjustment, stock_take, import_opening, assembly_out, assembly_in, disassembly_out, disassembly_in, sale, sale_void, credit_note, transfer_out, transfer_in, revaluation. Note that sale, sale_void, credit_note are only ever CREATED by a perpetual company — a company that has since switched to periodic still holds the ones it wrote (and a void of one of those documents still writes its reversal leg)."
  2. Changed2 schema fields changed
    • changedInput schema / properties / from / description
      Previous value: -"Earliest movement date (YYYY-MM-DD, Malaysian time). The main way to break a >200-row pull into honest slices."New value: +"Earliest docDate (YYYY-MM-DD; the document date, else the Malaysian posting day). The main way to break a >200-row pull into honest slices."
    • changedInput schema / properties / to / description
      Previous value: -"Latest movement date (YYYY-MM-DD, Malaysian time)."New value: +"Latest docDate (YYYY-MM-DD; the document date, else the Malaysian posting day)."
  3. Changed1 schema field changed
    • changedInput schema / properties / sourceType / description
      Previous value: -"Exactly one movement cause. One of: purchase, purchase_void, debit_note, debit_note_void, adjustment, stock_take, import_opening, assembly_out, assembly_in, disassembly_out, disassembly_in, sale, sale_void, credit_note, transfer_out, transfer_in. Note that sale, sale_void, credit_note only ever exist in a perpetual company."New value: +"Exactly one movement cause. One of: purchase, purchase_void, debit_note, debit_note_void, adjustment, stock_take, import_opening, assembly_out, assembly_in, disassembly_out, disassembly_in, sale, sale_void, credit_note, transfer_out, transfer_in. Note that sale, sale_void, credit_note are only ever CREATED by a perpetual company — a company that has since switched to periodic still holds the ones it wrote (and a void of one of those documents still writes its reversal leg)."
  4. Changed1 schema field changed
    • changedInput schema / properties / sourceType / description
      Previous value: -"Exactly one movement cause. One of: purchase, purchase_void, debit_note, debit_note_void, adjustment, stock_take, import_opening, assembly_out, assembly_in, disassembly_out, disassembly_in, sale, sale_void, credit_note, transfer_out, transfer_in. Note that sale, sale_void, credit_note only ever exist in a perpetual workspace."New value: +"Exactly one movement cause. One of: purchase, purchase_void, debit_note, debit_note_void, adjustment, stock_take, import_opening, assembly_out, assembly_in, disassembly_out, disassembly_in, sale, sale_void, credit_note, transfer_out, transfer_in. Note that sale, sale_void, credit_note only ever exist in a perpetual company."
  5. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true and openWorldHint=false. The description goes far beyond, disclosing field semantics (qtyDelta signed, balanceAfter as recorded), edge cases (editReversal on void rows, stock_take pairs netting to zero, adjustment ambiguity), stock-mode caveats (modified_periodic vs perpetual), pagination behavior ('capped at 200 with total, shown and more'), and the guarantee that 'Nothing is written, and no draft is created.'

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

Conciseness4/5

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

The description is long but front-loads the core purpose and then organizes caveats into clear sections. Given the absence of an output schema, much of the length is justified to explain row semantics and edge cases. However, some parenthetical details (e.g., date nuances for voided documents) could be tightened, so it is not maximally concise.

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?

With no output schema, the description fully explains the return value: field-by-field row structure, ordering (newest first), pagination (capped at 200 with total/shown/more), and the meaning of stockMode. It also clarifies what the tool does not return and routes to siblings for those needs, leaving no essential gap for an agent to call it correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all filter parameters; baseline is 3. The description repeats the filtering semantics ('product' case-insensitive contains name or SKU, 'from'/'to' as a docDate window, 'sourceType' exactly one cause) without adding syntax or format details beyond the schema. It does not mention the many decoy parameters the schema warns about, but those are schema-level concerns.

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?

States a specific verb and resource: 'Read the STOCK MOVEMENT LEDGER in bulk — every recorded change to on-hand quantity, across products, in one call.' It explicitly distinguishes from sibling stock_level ('says how many you have RIGHT NOW for one product; this says WHAT MOVED, WHEN, WHY and WHAT IT LEFT BEHIND') and names other non-overlapping siblings (balance_sheet, income_statement, profit_drivers, low_stock) in its exclusions.

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?

Gives concrete use cases (stock-turn analysis, shrinkage hunting, reorder timing, reconstructing balances) and states that every filter is optional with a bare call being a legitimate 'what moved lately' pull. It explicitly names when NOT to use it and which sibling to use instead: 'does not value your inventory (balance_sheet does), does not compute COGS or margin (income_statement, profit_drivers), and does not tell you what to reorder (low_stock).'

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.

Resources