Tools reference
All FOPilot MCP tools with their kind, purpose and metering.
- Read tools (
readOnlyHint: true):list_connections,np_find_city,np_find_warehouse,np_estimate_delivery,np_track_parcels,np_list_waybills,list_orders,get_order,get_daily_summary,reconcile_payments,checkbox_get_shift,checkbox_list_receipts,mono_get_balances,mono_get_statement,get_usage. - Write tools (additive only,
destructiveHint: false):np_create_waybill,np_create_waybills_bulk(dry_rundefaults to true),checkbox_open_shift. - Destructive tools (overwrite store data, irreversible or deleting,
destructiveHint: true):update_order_status,set_order_waybill,update_product_stock,np_delete_waybill,checkbox_create_receipt,checkbox_create_return_receipt,checkbox_close_shift.
Every tool that calls a third-party API costs 1 action; bulk waybill creation costs 1 action per created waybill; list_connections and get_usage are free. No tool transfers money.
checkbox_get_shift
read-onlyService actionsGet the Checkbox shift
Returns the cashier's current Checkbox shift: status, opening time and hours open, cash register fiscal number, cashier, number of receipts, and sales and returns totals.
- connection_id (string | null) — Checkbox connection id
checkbox_list_receipts
read-onlyService actionsList Checkbox receipts
Lists fiscal receipts of a period (up to 31 days, newest first) with fiscal codes, totals, payment types and links, plus the period's sales and returns totals.
- date_from (string | null) — Start day YYYY-MM-DD; default today
- date_to (string | null) — End day YYYY-MM-DD; default date_from
- receipt_type (string) — Receipt type filter
- limit (integer) — Receipts per page
- cursor (string | null) — next_cursor from the previous page
- connection_id (string | null) — Checkbox connection id
get_daily_summary
read-onlyService actionsDaily summaryGet the daily summary
Summarises one day across all connected services: orders per store and status, orders without a waybill for over 24 hours, Nova Poshta parcels of the last 14 days by status, cash on delivery awaiting, pending payout, paid out and returned, the Checkbox shift and receipts, monobank income, and alerts. Each service is queried separately; a failing one is reported in the result.
- day (string | null) — Day YYYY-MM-DD (Kyiv time); default today
get_order
read-onlyService actionsGet order details
Returns one order with items, payment, delivery details, waybill number and the statuses the order can be moved to. Contacts are masked unless reveal_contacts is true.
- order_ref * (string) — Order reference, e.g. prom:312874561
- reveal_contacts (boolean) — Return the buyer's full name, phone and e-mail instead of masked values
get_usage
read-onlyGet plan and usage
Returns the organization's current plan, subscription status, usage of each metered limit in the current billing period, object caps and the plan's features.
list_connections
read-onlyList connected services
Lists the services connected to the organisation (Nova Poshta, stores, Checkbox, monobank), their status and whether they are demo connections, plus which providers are not connected and whether the shipping settings needed for waybills are complete.
list_orders
read-onlyService actionsList store orders
Lists orders from the connected stores (Prom.ua, Horoshop, Rozetka, KeyCRM) merged into one list, newest first, with unified and store statuses, totals, payment, delivery city/branch and waybill number. Buyer names are shortened and phones masked.
- store (string | null) — Connection id or platform (prom, horoshop, rozetka, keycrm); default all
- status (object | null) — Unified status: new, processing, shipped, delivered, completed, canceled, returned
- created_from (string | null) — YYYY-MM-DD; default 30 days ago
- created_to (string | null) — YYYY-MM-DD; default today
- unshipped_only (boolean) — Only new/processing orders without a waybill number
- limit (integer)
- cursor (string | null) — next_cursor of the previous page
mono_get_balances
read-onlyService actionsGet monobank balances
Returns monobank accounts (FOP and card accounts) with balance, credit limit and own funds, masked IBANs and card numbers, and jars with their balances and goals. Read-only.
- connection_id (string | null) — monobank connection id
mono_get_statement
read-onlyService actionsGet a monobank statement
Returns monobank statement lines of one account for a period of up to 31 days: time, amount, purpose, comment and counterparty (names shortened, card and phone numbers masked), with incoming and outgoing totals. monobank permits one request per minute per token, so the call can take up to a minute. Read-only.
- account_id (string | null) — Account id from mono_get_balances; default the FOP (or first UAH) account
- date_from (string | null) — Start day YYYY-MM-DD; default 7 days ago
- date_to (string | null) — End day YYYY-MM-DD; default today
- direction (string) — Filter by money direction
- limit (integer) — Maximum lines returned (newest first)
- connection_id (string | null) — monobank connection id
np_estimate_delivery
read-onlyService actionsEstimate Nova Poshta delivery
Calculates the Nova Poshta delivery price (including the cash-on-delivery fee) and the estimated delivery date between two cities for a parcel of the given weight and declared value.
- city_to * (string) — Destination city Ref or name
- weight_kg * (number | string) — Parcel weight, kg
- declared_value * (number | string) — Declared value, UAH
- cod_amount (number | string | null) — Cash-on-delivery amount, UAH
- city_from (string | null) — Origin city Ref or name; default: the sender city from settings
- to_postomat (boolean) — Delivery to a parcel locker
- ship_date (string | null) — Shipping date YYYY-MM-DD; default today
- connection_id (string | null) — Nova Poshta connection id from list_connections; default: the main one
np_find_city
read-onlyService actionsFind a Nova Poshta city
Searches the Nova Poshta settlement directory by name and returns matching settlements with their city Ref, region, settlement type and number of Nova Poshta branches.
- query * (string) — Settlement name, e.g. 'Київ', 'Біла Церква'
- limit (integer) — Maximum results
- connection_id (string | null) — Nova Poshta connection id from list_connections; default: the main one
np_find_warehouse
read-onlyService actionsFind Nova Poshta branches
Lists Nova Poshta branches and parcel lockers of a city, optionally filtered by branch number or street, with their Ref, number, type, weight limit and whether they currently accept parcels.
- city * (string) — City Ref from np_find_city, or a city name
- query (string | null) — Branch number ('12') or street ('Хрещатик')
- kind (string) — Filter by point type
- limit (integer)
- connection_id (string | null) — Nova Poshta connection id from list_connections; default: the main one
np_list_waybills
read-onlyService actionsList my Nova Poshta waybills
Lists waybills created by the connected Nova Poshta sender in a date range (up to 31 days) with status, destination, amounts and short-lived links to print the waybill PDF.
- date_from (string | null) — Created from, YYYY-MM-DD; default 7 days ago
- date_to (string | null) — Created to, YYYY-MM-DD; default today
- limit (integer)
- cursor (string | null) — next_cursor of the previous page
- connection_id (string | null) — Nova Poshta connection id from list_connections; default: the main one
np_track_parcels
read-onlyService actionsTrack Nova Poshta parcels
Returns the current tracking status of Nova Poshta waybills: where the parcel is, delivery and receipt dates, cash-on-delivery amount and payout state, return waybill and paid-storage date. Recipient names are shortened and phones masked.
- numbers * (array) — Waybill numbers (ТТН), up to 100
- phone (string | null) — Sender or recipient phone for parcels of other senders
- connection_id (string | null) — Nova Poshta connection id from list_connections; default: the main one
reconcile_payments
read-onlyService actionsPayment reconciliationReconcile payments with orders
Matches incoming monobank transactions of a period (up to 31 days) with store orders paid by card or bank transfer and with Nova Poshta cash-on-delivery payouts. Returns matched payments with method and confidence, ambiguous ones with candidates, unmatched transactions, orders still unpaid, parcels received without a payout, and payouts missing in the statement. monobank permits one request per minute per token, so the call can take up to a minute. Read-only.
- date_from (string | null) — Period start YYYY-MM-DD; default 7 days ago
- date_to (string | null) — Period end YYYY-MM-DD; default today
- store (string | null) — Limit orders to one store connection id or platform
- account_id (string | null) — monobank account id; default the FOP (or first UAH) account
- mono_connection_id (string | null) — monobank connection id
checkbox_open_shift
writeService actionsOpen a Checkbox shift
Opens a cashier shift on the Checkbox cash register (needs the cash register license key in the connection). Returns the current shift unchanged when one is already open.
- connection_id (string | null) — Checkbox connection id
np_create_waybill
writeService actionsCreate a Nova Poshta waybill for an order
Creates a Nova Poshta waybill (ТТН) for a store order: resolves the city and branch from the order, applies the sender and parcel defaults, adds cash on delivery for unpaid cash-on-delivery orders and writes the waybill number back to the order. When the city or branch is ambiguous it creates nothing and returns the candidates (status needs_choice).
- order_ref * (string) — Order reference from list_orders, e.g. prom:312874561
- warehouse_ref (string | null) — Branch/parcel-locker Ref chosen among candidates
- city_ref (string | null) — City Ref chosen among candidates
- weight_kg (number | string | null) — Weight; default from settings
- seats (integer | null) — Number of parcels (seats)
- length_cm (number | string | null)
- width_cm (number | string | null)
- height_cm (number | string | null)
- declared_value (number | string | null) — Declared value; default = order total
- cod_amount (number | string | null) — Cash on delivery; 0 disables it
- description (string | null) — Cargo description
- payer (string | null) — Who pays for delivery
- ship_date (string | null) — Shipping date YYYY-MM-DD; default today
- connection_id (string | null) — Nova Poshta connection id from list_connections; default: the main one
np_create_waybills_bulk
writeService actionsBulk waybillsPlan or create Nova Poshta waybills in bulk
Builds a waybill plan for many orders (dry run, default) or creates the waybills of a previous plan. The plan lists for every order whether it is ready, needs a city/branch choice (with candidates), is skipped (already has a waybill, cancelled, other carrier, courier delivery) or has an error, plus the cash-on-delivery total. Creation costs one action per created waybill and writes the numbers back to the stores.
- dry_run (boolean) — true (default): only build a plan; false: create the ready items of plan_id
- plan_id (string | null) — plan_id returned by a dry run (required when dry_run=false)
- order_refs (array | null) — Orders to include; default: open orders without a waybill
- store (string | null) — Limit to one store connection id or platform (prom, rozetka …)
- created_from (string | null) — Orders created from YYYY-MM-DD; default 7 days ago
- choices (object | null) — Corrections for needs_choice items: {order_ref: {warehouse_ref, city_ref}}
- limit (integer)
- connection_id (string | null) — Nova Poshta connection id from list_connections; default: the main one
checkbox_close_shift
destructiveService actionsClose the Checkbox shift (Z-report)
Closes the open Checkbox shift, which creates the fiscal Z-report (irreversible). Returns the closed shift with the Z-report fiscal code, receipt counts, and sales and returns totals.
- connection_id (string | null) — Checkbox connection id
checkbox_create_receipt
destructiveService actionsCreate a fiscal sale receipt
Creates and fiscalizes a sale receipt on the open Checkbox shift (irreversible: a fiscal receipt can only be compensated by a return receipt). Lines come from a store order or are given explicitly; amounts are sent in kopiyky. Returns the fiscal code, total and receipt links.
- payment_type * (string) — CASHLESS (card, bank transfer, online payment) or CASH
- order_ref (string | null) — Order reference from list_orders whose lines and total are used
- lines (array | null) — Receipt lines when no order is given
- paid_total (number | string | null) — Amount paid, UAH; less than the lines' sum becomes a discount
- email_order_customer (boolean) — Send the receipt to the email stored in the order
- footer (string | null) — Text printed at the bottom
- allow_repeat (boolean) — Create even if a sale receipt for this order was created here in 30 days
- connection_id (string | null) — Checkbox connection id
checkbox_create_return_receipt
destructiveService actionsCreate a fiscal return receipt
Creates and fiscalizes a return (refund) receipt on the open Checkbox shift (irreversible), linked to the original sale receipt when its id is given. Returns the fiscal code and total. The refund itself is not sent by this tool.
- receipt_id (string | null) — Id of the original sale receipt; without lines all its lines are returned
- lines (array | null) — Returned lines (partial return)
- payment_type (string | null) — CASHLESS or CASH; default: the original receipt's payment type
- refund_total (number | string | null) — Amount refunded, UAH; less than the lines' sum becomes a discount
- connection_id (string | null) — Checkbox connection id
np_delete_waybill
destructiveService actionsDelete a Nova Poshta waybill
Deletes a Nova Poshta waybill that has not yet been handed over to Nova Poshta. Irreversible. Waybills already accepted at a branch cannot be deleted.
- ttn * (string) — Waybill number (14 digits) created in the last 30 days
- connection_id (string | null) — Nova Poshta connection id from list_connections; default: the main one
set_order_waybill
destructiveService actionsAttach a waybill number to an order
Writes a waybill (tracking) number into a store order so the buyer can track the parcel (Prom.ua delivery declaration, Rozetka TTN, KeyCRM tracking code, Horoshop external tracking code).
- order_ref * (string) — Order reference, e.g. prom:312874561
- ttn * (string) — Waybill / tracking number (Nova Poshta: 14 digits)
update_order_status
destructiveService actionsChange order status
Changes the status of a store order. Accepts a unified status or a store-specific status id; Rozetka transitions are checked against the statuses allowed for the order.
- order_ref * (string) — Order reference, e.g. rozetka:745123456
- status * (string) — Unified status (new, processing, shipped, delivered, completed, canceled, returned) or the store's own status id from get_order
- reason (string | null) — Prom.ua cancellation reason: not_available, price_changed, buyers_request, not_enough_fields, duplicate, invalid_phone_number, less_than_minimal_price, another
- comment (string | null) — Comment (Prom 'another' reason text, manager comment)
update_product_stock
destructiveService actionsUpdate product stock and prices
Updates stock quantity, availability and price of products in Prom.ua (by product id or external SKU) or stock in KeyCRM (by SKU or offer id). Each product costs one action.
- store * (string) — Store connection id or platform: prom or keycrm
- items * (array) — Products by sku (external id) or product_id with quantity/price/available
- warehouse_id (integer | null) — KeyCRM warehouse id (default from the connection)