This page lists every tool the facturillo connector offers an AI assistant: what each one reads or changes and who may call it. It is for people who connect Claude or ChatGPT and for reviewers of AI assistant directories. The connector address and the steps to connect it are in the connection guide. Which tools an assistant sees depends on the account: a paid account with the Write permission turned on and a connection for reading and adding sees all 34.

How to read the classes

Each tool carries a class next to its name.

  • Read: the tool only reads.
  • Write: it adds or changes data.
  • Sensitive write: it removes, replaces or moves something. Assistants usually ask you before running one.

The MCP annotations shown for each tool (readOnlyHint and destructiveHint) are what the assistant reads to decide when to ask you.

Rules common to every tool

Status handling. Every tool returns an MCP tool result with structuredContent and a JSON text copy. A refusal is a tool result with isError: true and a bilingual text (Spanish and English), never an HTTP error, so the assistant can tell you the reason.

Errors common to every tool. The server sends each text in Spanish and English. They are quoted here in English.

  • Rate limit: "Too many requests in a row, wait a moment and retry."
  • Data service unavailable (facturas and income tools): "The data service is temporarily unavailable, retry in a few minutes."
  • Input refusal: an unknown or invalid argument is refused with the reason, before the tool runs.
  • Daily price quota (price tools): the refusal names the plan and when it resets, and on Free it adds "A Pro plan raises the daily limit."
  • Tools that add facturas: "This account does not have Write permission turned on.", "This account is read-only (subscription lapsed).", "Daily AI-add limit reached. Try again tomorrow or add it in the app."

Rate limits.

  • Per account, per server instance: a token bucket of 60 that refills at 0.5 tokens a second. Cheap reads cost 1 token, and spending_summary and vendors_summary cost 5.
  • Price calls per day, by plan: Free 30, Pro 300, Business 1,000, Cuestio no daily cap. Exports per day: Business 10, Cuestio 50. These are the default values and the live configuration can change them.
  • Facturas added through AI: 50 per account per day.

Account and contexts

whoami · Read

  • Returns: the account id and its plan (free or paid). On a free plan it adds one line on what the plan includes.
  • Inputs (* required): none
  • Output fields: uid, tier, message
  • Who can call it: any connected facturillo account
  • Side effects: none, it only reads.
  • Errors: rate limit, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

list_contexts · Read

  • Returns: the contexts the account can query: personal, business, and linked family or business accounts.
  • Inputs (* required): none
  • Output fields: contexts
  • Who can call it: paid plan, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

Online prices

price_search · Read

  • Returns: matching products, each with its store count, the cheapest and the dearest store and price, paged by cursor.
  • Inputs (* required): query*, limit, cursor
  • Output fields: products, total, relaxed, cursor, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, daily price quota reached, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

price_offers · Read

  • Returns: every current online offer for one product, cheapest first: store, branch, price, previous price, product page, the day read and the day changed, and stock flags on request.
  • Inputs (* required): product*, includeOutOfStock, stock, include_hidden
  • Output fields: product, offers, notes, storeCount, offerCount, hidden_count, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, daily price quota reached, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

price_history · Read

  • Returns: one product's online price per store as runs of a constant price or one point per day. The last 30 days by default, at most 400 days.
  • Inputs (* required): product*, stores, from, to, granularity
  • Output fields: product, from, to, granularity, series, clampedTo, sparseBefore, note, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, daily price quota reached, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

price_basket · Read

  • Returns: each store's total over the products it prices, the products it misses, the cheapest store and a paged price matrix.
  • Inputs (* required): products, basketId, watchList, stores, inStockOnly, limit, cursor
  • Output fields: scope, stores, cheapestStore, matrix, total, cursor, unmatched, unmatchedCount, unpriced, unpricedCount, notes, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, daily price quota reached, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

price_changes · Read

  • Returns: price cuts, rises, new offers and delistings over one scope, each with the price before and after, the change in percent and its day.
  • Inputs (* required): scope*, from, to, kinds, limit, cursor
  • Output fields: changes, counts, window, total, cursor, scope, scopeKind, notes, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:read, Pro plan and above
  • Side effects: none, it only reads.
  • Errors: rate limit, daily price quota reached, plan refusal, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

price_watch · Sensitive write

  • Returns: the watch list's items (action list), or the list after a set, add or remove.
  • Inputs (* required): action*, items, limit, cursor
  • Output fields: action, items, total, cursor, count, removed, watchMax, used, unresolved, notes, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:write, Business and Cuestio plans
  • Side effects: set replaces the whole list, add merges items in, remove takes items out, list changes nothing.
  • Errors: rate limit, daily price quota reached, plan refusal, input refusal
  • Annotations: readOnlyHint false, destructiveHint true

price_index · Read

  • Returns: per competitor the matched products, the median and mean price ratio, the shares cheaper, dearer and equal, and the ten biggest gaps each way.
  • Inputs (* required): reference*, competitors, scope, inStockOnly
  • Output fields: reference, competitors, inStockOnly, scope, scopeKind, notes, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:read, Cuestio plan
  • Side effects: none, it only reads.
  • Errors: rate limit, daily price quota reached, plan refusal, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

price_promotions · Read

  • Returns: the live promotions of the online supermarkets, each with its depth in percent, its start day and its store.
  • Inputs (* required): stores, scope, from, to, rule, includeEnded, limit, cursor
  • Output fields: promotions, counts, byStore, suspectPromotions, window, rule, includeEnded, total, cursor, scope, scopeKind, notes, quota, asOf, sources, partial
  • Who can call it: an account with price access, scope receipts:read, Cuestio plan
  • Side effects: none, it only reads.
  • Errors: rate limit, daily price quota reached, plan refusal, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

price_availability · Read

  • Returns: per product and store whether it is listed, its online stock flag, its price and day, plus a summary per store.
  • Inputs (* required): brand, basketId, watchList, products, stores, limit, cursor
  • Output fields: products, summary, total, cursor, scope, notes, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:read, Cuestio plan, and Business for its own watch list or baskets
  • Side effects: none, it only reads.
  • Errors: rate limit, daily price quota reached, plan refusal, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

price_export · Write

  • Returns: a private download link to a CSV file of one price report, valid 15 minutes, in parts above 200,000 rows.
  • Inputs (* required): report*, args, format, part
  • Output fields: report, part, parts, rows, bytes, url, expiresAt, exportBudget, quota, asOf, sources, partial
  • Who can call it: an account with price access, scope receipts:write, plans with an export budget (Business and Cuestio by default)
  • Side effects: writes a CSV file on facturillo's server behind a private link that expires after 15 minutes, deletes the file after a day, and counts against the plan's export budget.
  • Errors: rate limit, daily price quota reached, plan refusal, export budget, input refusal
  • Annotations: readOnlyHint false, destructiveHint false

price_stores · Read

  • Returns: the online stores covered, with banners, branches, offer and product counts, main categories and whether each publishes stock.
  • Inputs (* required): none
  • Output fields: stores, total, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, daily price quota reached, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

Baskets

basket_list · Read

  • Returns: the account's baskets (name, icon, color, line count, last refresh, best buy), or one basket with its products.
  • Inputs (* required): basketId, limit, cursor
  • Output fields: baskets, total, cursor, basket, lines, caps, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, daily price quota reached, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

basket_create · Write

  • Returns: the new basket, each product's result (added, duplicate, capReached, notFound) and the plan's caps.
  • Inputs (* required): name*, icon, color, products
  • Output fields: basketId, name, lines, linesAdded, notes, caps, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:write
  • Side effects: creates a basket in the account, shown in the facturillo app at once.
  • Errors: rate limit, daily price quota reached, basket caps, input refusal
  • Annotations: readOnlyHint false, destructiveHint false

basket_add_products · Write

  • Returns: each product's result (added, duplicate, capReached, notFound or error) and the basket after the change.
  • Inputs (* required): basketId*, products*
  • Output fields: basketId, results, lineCount, linesMax, notes, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:write
  • Side effects: adds product lines to one basket, shown in the app.
  • Errors: rate limit, daily price quota reached, basket caps, input refusal
  • Annotations: readOnlyHint false, destructiveHint false

basket_remove_product · Sensitive write

  • Returns: the basket's line count after the change.
  • Inputs (* required): basketId*, product*
  • Output fields: basketId, removed, lineCount, notes, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:write
  • Side effects: removes one product line from one basket.
  • Errors: rate limit, daily price quota reached, basket caps, input refusal
  • Annotations: readOnlyHint false, destructiveHint true

basket_delete · Sensitive write

  • Returns: the plan's caps after the change.
  • Inputs (* required): basketId*
  • Output fields: basketId, deleted, caps, quota, asOf, sources
  • Who can call it: an account with price access, scope receipts:write
  • Side effects: deletes one basket from the account and the app.
  • Errors: rate limit, daily price quota reached, basket caps, input refusal
  • Annotations: readOnlyHint false, destructiveHint true

Facturas and spending

receipts_search · Read

  • Returns: matching facturas, 20 per page by default and 50 at most, each with an attachment flag.
  • Inputs (* required): context, date_from, date_to, vendor_query, text_query, vendor_category, product_category, min_total, max_total, has_attachment, cursor, page_size, response_format
  • Output fields: receipts, nextCursor, notice, processingCount
  • Who can call it: paid plan, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

receipts_get · Read

  • Returns: one factura: header, totals, payment methods, attachment availability and consolidated line items.
  • Inputs (* required): context, receipt_id*, include_items
  • Output fields: receipt
  • Who can call it: paid plan, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

spending_summary · Read

  • Returns: totals, counts or averages grouped by vendor, category, month, week, day or payment method.
  • Inputs (* required): context, metric, group_by, date_from, date_to
  • Output fields: metric, group_by, rows, notice, processingCount
  • Who can call it: paid plan, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

products_search · Read

  • Returns: purchased product lines with price, vendor, date and receipt id, paged.
  • Inputs (* required): context, query, vendor_query, date_from, date_to, cursor, page_size
  • Output fields: products, nextCursor, notice
  • Who can call it: paid plan, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

vendors_summary · Read

  • Returns: per vendor the facturas count, total spent, average ticket and first and last visit, the top 60 by total.
  • Inputs (* required): context, vendor_query, date_from, date_to
  • Output fields: vendors, notice
  • Who can call it: paid plan, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

receipt_attachments · Read

  • Returns: the factura's documents as download links valid 15 minutes, and the files inline on request.
  • Inputs (* required): context, receipt_id*, include_content
  • Output fields: receiptId, attachments, notice, dgiPdfUnavailable
  • Who can call it: paid plan, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

Income

income_search · Read

  • Returns: the business's issued invoices and manual income entries, paged.
  • Inputs (* required): context, q, from, to, category, client, doc_type, min_total, max_total, cursor, limit
  • Output fields: incomes, nextCursor, notice
  • Who can call it: paid plan, scope receipts:read, a business account's main context with owner or superadmin access
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

income_get · Read

  • Returns: one income document with the product lines it sold.
  • Inputs (* required): context, id*, include_items
  • Output fields: income
  • Who can call it: paid plan, scope receipts:read, a business account's main context with owner or superadmin access
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

income_summary · Read

  • Returns: the business's sales as a total, count, tax or average ticket, grouped as asked.
  • Inputs (* required): context, from*, to*, metric, group_by
  • Output fields: metric, group_by, rows, notice
  • Who can call it: paid plan, scope receipts:read, a business account's main context with owner or superadmin access
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

income_products_search · Read

  • Returns: the products the business sold, with line and document counts, quantity, net income and last price, paged.
  • Inputs (* required): context, q, category, from, to, cursor, limit
  • Output fields: products, nextCursor, notice
  • Who can call it: paid plan, scope receipts:read, a business account's main context with owner or superadmin access
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

Search for ChatGPT

search · Read

  • Returns: up to 20 facturas (id and title).
  • Inputs (* required): query*
  • Output fields: results, processingNote
  • Who can call it: paid plan, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

fetch · Read

  • Returns: one factura as document text, with consolidated line items.
  • Inputs (* required): id*
  • Output fields: id, title, text, url, metadata
  • Who can call it: paid plan, scope receipts:read
  • Side effects: none, it only reads.
  • Errors: rate limit, data service unavailable, input refusal
  • Annotations: readOnlyHint true, destructiveHint false

Adding facturas

receipts_add_dgi · Sensitive write

  • Returns: the added factura's processing status, or the existing factura when it is already in one of the user's accounts.
  • Inputs (* required): context, url, cufe, move
  • Output fields: receiptId, status, alreadyExists, existingContext, canMove, moved, notice
  • Who can call it: paid plan, scope receipts:write, Write permission turned on in the app (and on the target account)
  • Side effects: adds a factura (scanned in the background), and with move true it moves a factura from the personal account into the named account.
  • Errors: rate limit, data service unavailable, Write permission off, account read-only, daily limit of facturas added by AI, input refusal
  • Annotations: readOnlyHint false, destructiveHint true

receipts_add_manual · Write

  • Returns: the factura added from the typed details.
  • Inputs (* required): context, title*, date*, total*, tax, category*, fine_category, note, currency, tax_id, lines
  • Output fields: receiptId, status, totalUsd, originalTotal, originalCurrency, exchangeRate, notice
  • Who can call it: paid plan, scope receipts:write, Write permission turned on in the app (and on the target account)
  • Side effects: adds a factura from typed details, and a foreign-currency amount is converted to USD at the day's rate.
  • Errors: rate limit, data service unavailable, Write permission off, account read-only, daily limit of facturas added by AI, input refusal
  • Annotations: readOnlyHint false, destructiveHint false

receipts_add_upload · Write

  • Returns: a one-time upload link for the user's phone and an upload id.
  • Inputs (* required): context
  • Output fields: uploadUrl, uploadId, expiresInSec, notice
  • Who can call it: paid plan, scope receipts:write, Write permission turned on in the app (and on the target account)
  • Side effects: creates a one-time upload link, and the photo the user sends is added as a factura in the background.
  • Errors: rate limit, data service unavailable, Write permission off, account read-only, daily limit of facturas added by AI, input refusal
  • Annotations: readOnlyHint false, destructiveHint false

receipts_add_status · Write

  • Returns: the upload's status (waiting-for-upload, processing, done, needs-review, exists-elsewhere, expired or failed) and the receipt id once added.
  • Inputs (* required): upload_id*
  • Output fields: status, receiptId, processId, reason, message, notice
  • Who can call it: paid plan, scope receipts:write, Write permission turned on in the app (and on the target account)
  • Side effects: reads the upload's status and records the result on the factura it created.
  • Errors: rate limit, data service unavailable, Write permission off, account read-only, daily limit of facturas added by AI, input refusal
  • Annotations: readOnlyHint false, destructiveHint false

If you have a question about a tool, write to support@facturillo.com.