Skip to main content
Glama

Taokeh MCP server

by my.taokeh
OverviewAdmin

File credit-note draft

create_credit_note_draft

File a CREDIT NOTE draft into Taokeh — a sales return, short delivery, price correction or allowance that reduces what a customer owes. This does NOT post to the books: it creates a pending draft the user reviews and approves in Taokeh, and only then does it reduce the customer's balance, reverse the revenue and SST, and (if the user says the goods came back) put stock back. Shape the fields with intake_contract(doc_type:'credit_note') first. RESOLVE THE ORIGINAL INVOICE FIRST: a credit note is issued AGAINST an invoice — find it with search_documents and pass its id as originalDocId with kind:'against_invoice'. Only a credit with NO source invoice is kind:'allowance', and an allowance is never linked to an invoice, never capped by one, inherits no SST codes and never restocks — so do not file a real return as one; ask the user which invoice it is against. Send all amounts POSITIVE (Taokeh stores the credit note negative itself). A line can only credit back as MANY units as that invoice actually sold, net of earlier credit notes — an over-quantity line is refused naming what is left, so read the invoice's own unit of measure rather than converting it (1 carton is not 100 pieces). Whether goods physically came back into stock is the USER's decision at approval — goodsReturned is only a hint that pre-ticks their checkbox on the full review page, and a one-tap approval always posts money-only. Set needsReview and add a SHORT reviewer note in notes (one or two sentences naming what to double-check) for any doubt. Filed it wrong? Use revise_draft (kind: 'credit_note') rather than filing a second one. IS A CREDIT NOTE EVEN THE RIGHT DOCUMENT? Only when something CHANGED AFTER the sale — goods came back, a price was renegotiated, a discount was agreed later. If the sale simply never happened (keyed twice, wrong company, cancelled before delivery), the owner VOIDS the invoice instead: Sales → the invoice → Void, in Taokeh. There is deliberately no AI lane for voiding. And if the sale did happen but the invoice was typed wrong — wrong line, wrong quantity or price, wrong date — that is a correction, not a credit: use update_invoice_draft. ⛔ LINE KEYS ARE STRICT (2026-09-09): a key this schema does not list is REFUSED BY NAME — with the key it probably meant — and NOTHING is filed. Unknown keys used to be dropped in silence, which let a line through with its price or its tax code missing.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
kindYesREQUIRED. 'against_invoice' = a return / short delivery / price correction on a SPECIFIC invoice (the usual case — give originalDocId or originalDocNumber). 'allowance' = a standalone money credit with NO source invoice (give the customer instead). They are different documents; when it isn't clear, ask the user which invoice it is against.
linesYes
notesNoA SHORT reviewer note: one or two plain sentences, in the reviewer's language, naming what the human should double-check before approving — whether the goods actually came back, an ambiguous quantity, which invoice you matched it to. Not lengthy reasoning.
cnDateYes
reasonNoWhy the credit is given — 'damaged goods returned', 'short delivery', 'agreed price adjustment'. It prints on the credit note.
customerNoallowance ONLY: the customer name, resolved with resolve_customer first. A credit note reduces an EXISTING customer's balance and can never create a customer. For an against_invoice credit note the customer comes from the invoice — leave this out.
referenceNoThe credit-note number already printed on paper, if any. Leave it out and Taokeh numbers it (CN…).
customerIdNoallowance: the resolved customer id instead of the name.
needsReviewNo
printedTotalNoThe total printed on the paper, if any. Cross-check only — the server computes the real total and flags a mismatch on the approval screen.
goodsReturnedNoAn ADVISORY hint only: it pre-ticks the reviewer's 'the goods came back into stock' checkbox. It does NOT decide the stock movement — the human does, at approval. Ignored for an allowance (always money-only).
originalDocIdNoagainst_invoice: the ORIGINAL invoice's id, from search_documents. The server verifies it exists, is an INVOICE and whose it is — it never guesses.
originalDocNumberNoagainst_invoice: the printed invoice number, when you have no id. Refused if more than one document carries it — find the right one with search_documents.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed2 schema fields changed
    • addedInput schema / properties / lines / items / additionalProperties
      Added value: +false
    • addedInput schema / properties / lines / items / properties / description / description
      Added value: +"The line text as PRINTED on the document, when it says more than the product name does — a size, a grade, a job reference, a period covered. It rides onto the posted line and prints on the customer's copy, so send what the paper says rather than a tidier phrasing of your own. Leave it out when the product name already says it. This is TEXT, not a field: Taokeh has no column for a dimension, a grade or a variant, so anything of that kind belongs here."
  2. Added

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the all-false annotations, the description discloses crucial behavioral traits: the tool does NOT post to the books, it creates a pending draft that a human reviews/approves; only after approval does it reduce balance, reverse revenue/SST, and restock. It reveals that Taokeh stores amounts negative internally so the caller must send positives, that over-quantity lines are refused with a message naming the remaining available quantity, that goodsReturned only pre-ticks a checkbox and never decides stock movement, and that needsReview should be set with a short note. No annotation contradiction exists — readOnlyHint=false is consistent with a draft-creating 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.

Conciseness4/5

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

The description is long, but almost every sentence carries operational safety value for a financially high-stakes document type. It is front-loaded with the core purpose and the critical 'does NOT post to the books' caveat. It loses one point for being somewhat stream-of-consciousness — the allowance-vs-invoice rules, voiding guidance, and correction guidance could be grouped more tightly — yet the density of irreplaceable information justifies most of its length.

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?

For a 13-parameter financial tool with no output schema and all-false annotations, the description is exceptionally complete: it covers both kind variants and their constraints, the approval/side-effect model, amount sign conventions, quantity limits, the goodsReturned advisory semantics, reviewer-note expectations, and the full decision tree for when a credit note is the wrong document. The only minor gap is that it never states what the tool returns on success (draft id?), but given the emphasis on downstream human approval and revision paths, this does not materially impair an agent's ability to invoke and follow up correctly.

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?

At 77% schema coverage, the description still adds substantial meaning beyond the schema: kind is given a decision rule ('when it isn't clear, ask the user which invoice it is against'), originalDocId is tied to a resolution workflow (search_documents), quantity is constrained by what the invoice actually sold net of prior credit notes with an example warning against unit conversion, and goodsReturned/notes semantics are sharpened beyond their schema text. The description compensates for the uncovered parameters and enriches the covered ones.

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 names a specific verb (File), a specific resource (a CREDIT NOTE draft into Taokeh), and the document's financial meaning (sales return, short delivery, price correction, or allowance that reduces what a customer owes). It also distinguishes the tool from its siblings by explaining what it is NOT: not a voided invoice, not an invoice correction (update_invoice_draft), not a re-filing (revise_draft). An agent can tell exactly what this tool does without ambiguity.

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 gives explicit when-to-use guidance: a credit note is right only when something changed AFTER the sale. It names the alternatives with conditions — owner voids the invoice if the sale never happened, update_invoice_draft if the invoice was typed wrong, revise_draft if the draft was filed wrong — and even notes there is 'deliberately no AI lane for voiding'. It also instructs to shape fields with intake_contract and resolve the original invoice with search_documents first, making the invocation workflow explicit.

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

All Taokeh MCP server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources