Norman MCP Server

List all available tax reports.

Retrieve a specific tax report. Args: report_id: Public ID of the tax report to retrieve Returns: Tax report details

Validate a tax number for a specific region. Args: tax_number: Tax number to validate region_code: Region code (e.g., DE for Germany) Returns: Validation result

Generate a test Finanzamt preview for a tax report. Returns the preview as an inline PNG image (first page) plus a downloadUrl for the full PDF. The image is rendered directly in clients that support MCP ImageContent.

Submit a tax report to the Finanzamt. Args: report_id: Public ID of the tax report to submit Returns: Response from the submission request and a link to the tax report from reportFile to download. If response status is 403, it means a paid subscription is required to file the report.

Get list of available tax states. Returns: List of tax states

Get list of tax settings for the current company. Returns: List of company tax settings

Update a tax setting. Always generate a preview of the tax report @generate_finanzamt_preview before submitting it to the Finanzamt. Args: setting_id: Public ID of the tax setting to update tax_type: Type of tax (e.g. "sales"); Options: "sales", "trade", "income", "profit_loss" vat_type: VAT type (e.g. "vat_subject"), Options: "vat_subject", "kleinunternehmer", "vat_exempt" vat_percent: VAT percentage; Options: 0, 7, 19 start_tax_report_date: Start date for tax reporting (YYYY-MM-DD) reporting_frequency: Frequency of reporting (e.g. "monthly"), Options: "monthly", "quarterly", "yearly" Returns: Updated tax setting

Get tax statistics for the company. Returns: Company tax statistics data

Get the VAT amount for the next report period. Returns: VAT next report amount data

Dry-run rule conditions against recent transactions BEFORE creating the rule. Show the user a few of the returned matches so they can confirm the rule catches the right things. Returns: A sample of matching transactions and the total sampled count.

Get the user's Gewerbeanmeldung, if any. Call this FIRST. A "not found" response means there is none — offer to start one with create_gewerbe_registration. Otherwise resume from `sections.missing`. A non-empty `documents` list means the form was already generated.

Mark a bill as paid (``status="PAID"``) WITHOUT initiating a payment. Use this for bills that were already paid outside Norman (e.g. migrated bills) to clear them from the Bills view. To actually pay a bill via SEPA, use ``pay_bill`` instead. Args: bill_id: ID of the bill to mark paid Returns: Updated bill record

Search for transactions matching specified criteria. Args: description: Text to search for in transaction descriptions from_date: Start date in YYYY-MM-DD format to_date: End date in YYYY-MM-DD format min_amount: Minimum transaction amount max_amount: Maximum transaction amount category: Transaction category limit: Maximum number of results to return (default 100) no_invoice: Whether to exclude invoices no_receipt: Whether to exclude receipts status: Status of the transaction (UNVERIFIED, VERIFIED) cashflow_type: Cashflow type of the transaction (INCOME, EXPENSE) Returns: List of matching transactions with sensitive data removed

Create a new manual transaction. For SME companies (GmbH/UG), use company_category_id instead of category_id, and optionally set payment_date and payment_type for accrual accounting.

Update an existing transaction. For SME companies, use company_category_id and payment fields.

Detect category for a transaction using AI. Args: transaction_amount: Amount of the transaction transaction_description: Description of the transaction transaction_type: Type of transaction ("income" or "expense") Returns: Suggested category information for the transaction

Verify or unverify a transaction (finalize or unfinalize). Args: transaction_id: Public ID of the transaction to update verify: If True, verify (finalize) the transaction; if False, unverify (unfinalize) it Returns: Updated transaction information

Get a list of all clients for the company. Returns: List of clients with their details

Get detailed information about a specific client. Args: client_id: ID of the client to retrieve Returns: Detailed client information

Create a new client. Args: name: Client name or business name client_type: Type of client (defaults to "business"), Options: "business", "private" address: Client physical address zip_code: Client postal/zip code email: Client email address country: Client country code (e.g. "DE") vat_number: Client VAT number city: Client city phone: Client phone number Returns: Newly created client record

Update an existing client. Args: client_id: ID of the client to update name: Updated client name client_type: Updated client type ("business" or "private") address: Updated client physical address zip_code: Updated client postal/zip code email: Updated client email address country: Updated client country code (e.g. "DE") vat_number: Updated client VAT number city: Updated client city phone: Updated client phone number Returns: Updated client record

Delete a client. Args: client_id: ID of the client to delete Returns: Confirmation of deletion

List the company's automation rules together with usage stats and the plan's automation limit. Returns: Rules ordered by priority (first match wins) and a summary with match counts and the `limits` block (activeLimit/activeUsed).

Create an automation rule. Preview first with preview_rule. Send exactly one of category_id / company_category_id (freelancer vs SME). After creating, offer apply_rule_to_existing to also categorize the backlog. Returns: The created rule.

Update an automation rule. Only the provided fields change. Re-activating a rule counts against the plan's automation limit like creating one. Returns: The updated rule.

Delete an automation rule after the user confirms. Prefer disabling (update_rule with is_active=false) when the user may want it back. Returns: Deletion confirmation.

Run an existing rule over the company's uncategorized transactions and categorize every match now. Use after create_rule when the user also wants the backlog cleaned up. Returns: The number of transactions updated.

Automation execution log. status=awaiting_review lists the matches a review-first rule parked for the user's approval — show each one (rule name, transaction/invoice, planned actions) and let the user decide; never approve or dismiss without an explicit go-ahead. Returns: A sample of executions and the total sampled count.

Everything an agent prepared and is waiting on the user for, in one list: review-first automations, a prepared UStVA, an active workflow step. Use this for "what needs me?" instead of guessing across surfaces. Items with an executionId can be decided here (approve_rule_execution or dismiss_rule_execution) once the user says so; the rest carry a link to the screen that owns the decision. Returns: items and count.

Put back what an automation changed, newest action first, AFTER the user asked for it. Only a run that changed something can be undone, and only once. Actions that left the world outside the books - a notification, a queued reminder, a prepared payment - cannot be taken back and come back as "not reversible"; say so rather than implying the run was fully reverted. Returns: The execution, stamped revertedAt.

The prebuilt agents shelf with each card's state and counters: AI categorization, auto-enrichment, document reconciliation, invoice chasing, bill payments with approval, VAT-return readiness, client document chasing, the month-end close, the document collector, plus links to Tax Autopilot and recurring invoices. Returns: cards, each with key, kind, enabled and counters.

Turn a prebuilt agent on or off after the user asked for it. What that means depends on the card: a toggle card flips a pipeline, a rule card (invoice chasing, bill payments) materializes or parks a review-first rule, and a workflow card starts or abandons its run. Turning something on can be refused on a limited plan - relay the message instead of retrying. Returns: The card in its new state.

Approve an awaiting-review execution AFTER the user explicitly confirmed it: the rule's full action chain runs (category, VAT, reminder emails, ...). Returns: The execution with per-action results.

Reject an awaiting-review execution after the user said no. The target goes back through normal categorization, and this rule never re-claims the same target. Returns: The dismissed execution.

Get a list of bills (incoming supplier invoices / Eingangsrechnungen). Args: status: Optional status filter (e.g. "PAID", "OPEN") Returns: List of bills with their details

Get detailed information about a specific bill. Args: bill_id: ID of the bill to retrieve Returns: Detailed bill information

Update an existing bill. Currently supports changing the bill status — e.g. set ``status="PAID"`` to clear a migrated/already-paid bill from the Bills view. Args: bill_id: ID of the bill to update status: New status (e.g. "PAID") Returns: Updated bill record

Initiate a SEPA payment for a bill. ⚠️ This starts a REAL payment flow. Returns a ``paymentOrderId`` and a ``webformUrl`` the user must open to authorise the payment with their bank. Does not move money on its own, but begins the process — only call when the user has explicitly asked to pay. Args: bill_id: ID of the bill to pay account_id: ID of the bank account to pay from (required by the backend) execution_date: Optional payment execution date in YYYY-MM-DD format purpose: Optional payment purpose / reference text Returns: Payment order details including paymentOrderId and webformUrl

Delete a bill. Args: bill_id: ID of the bill to delete Returns: Confirmation of deletion

Get the user's active company incorporation (GmbH/UG founding), if any. Call this FIRST. A "not found" response means there is no active incorporation — offer to start one with create_incorporation. Otherwise resume: check `sections` for what's missing and continue there.

Get valid values for incorporation enum fields (label by value).

Start a new GmbH/UG incorporation for the current user. Section 1/5 begins here. Save `publicId` from the response for all subsequent calls. Fails with a validation error if an active incorporation already exists — use get_incorporation and continue it instead.

Section 1/5 — company basics. Any subset of fields; provided fields are validated. After saving the company name, nudge the user to check name availability themselves (Handelsregister search: https://www.handelsregister.de, IHK guidance) — Norman does not verify the name. The address may be skipped for now but is needed before notarization. Check `sections.company.missing` in the response for what's still required.

Section 3/5 — share capital. Validated against the legal form. The per-shareholder split is set on each shareholder (share_nominal_amount) and must sum up to this amount — `sections.capital.missing` will contain 'shareNominalSum' until it does.

Section 2/5 — add a shareholder (max 3 for the statutory Musterprotokoll). Collect all founders one by one. For natural persons: name, date of birth, nationality and residential address are required. For legal entities: Firma, Sitz, register court and register number. Returns the full record — check `sections.shareholders.missing` and `musterprotokoll.reasons`.

Update a shareholder (any subset of fields). Returns the full record.

Send (or resend) a secure fill-your-details link to a co-founder. The invited shareholder completes their own personal data (name, date of birth, address) via the link — useful when the user doesn't have the co-founder's details at hand. Natural persons only. The link is valid for 30 days.

Remove a shareholder. Remaining shareholders are renumbered automatically.

Section 4/5 — founding agreement type. 'musterprotokoll' (the statutory template — fastest and cheapest) is only accepted when `musterprotokoll.eligible` is true (≤3 shareholders, exactly one managing director, capital bounds, nominal split matches). Otherwise explain the `reasons` codes to the user and set 'individual' — the notary drafts an individual Satzung.

Section 5/5 — notary preferences (city, online vs in person, timeframe).

Generate the founding document drafts (PDF): Musterprotokoll (when selected) and the Gesellschafterliste (§ 40 GmbHG). REQUIRES sections company, shareholders, capital and agreement to be complete — summarize all collected data and get the user's explicit confirmation BEFORE calling. ALWAYS tell the user the documents are auto-generated templates to prepare the notary appointment — NOT legal advice; the notary produces the binding versions. Returns download URLs. If the user later changes data, `documentsStale` becomes true — offer to regenerate.

Show the user a first-page image of a generated founding document for review.

Get up to 3 notaries matching the collected preferences (online capability, city). Present them to the user as options; they can pick one or request a match without picking (the Norman team assigns one).

Final step — request the notary hand-off. REQUIRES generated documents. Get the user's explicit confirmation before calling. The Norman team coordinates the appointment and gets back to the user; nothing is sent to a notary automatically. After this succeeds, present the remaining formation steps from the record's `roadmap` and invite the user back into the product to continue: their Norman dashboard at https://app.norman.finance/ has the formation roadmap (bank account, deposit, HRB, Finanzamt, Gewerbeamt, Transparency) where they track and complete each step.

Reformulate a rough business purpose (Unternehmensgegenstand) into registry-ready wording. Returns {"suggestion": ...} — a faithful, same-language rewrite: concrete activities, no catch-all phrases ("all permitted activities"), no licensable activities unless the draft states them, nothing invented. ALWAYS show it to the user and let them accept or keep their own text; never auto-apply. To use it, pass it to update_incorporation_company as business_purpose.

Search the German commercial register (Handelsregister) for similar company names. Returns {"status": "ok"|"unavailable", "searched", "matches": [{name, seat, register}]}. `status == "unavailable"` means the portal could not be queried — tell the user to check manually via handelsregister.de, do NOT infer the name is free. Existing matches mean a similar name may be rejected; the final say is with the registry court and the IHK.

Tick a post-notary formation roadmap step done/undone (steps 3-9 of the journey). The record's `roadmap` lists the 7 steps with their `done`/`active` state — drive from it. These are founder self-marks: they do NOT send the ops milestone emails and never move the official `status` backwards. The 'hrb' step optionally records the register number/court. Returns the full updated record (with the refreshed `roadmap`).

Generate a short-lived upload link that the USER opens in their browser. Call this BEFORE create_attachment when the user wants to attach a file (image, PDF, receipt) and you cannot provide a public file_url. The link opens a drag-and-drop upload page. After the user uploads, the page shows a file_ref token. Use that file_ref in create_attachment. IMPORTANT: Do NOT try to upload the file yourself (curl, base64, etc.). Just give the link to the user and wait for them to upload.

Upload multiple file attachments in bulk. Priority: file_urls > file_refs > files_base64. Do NOT base64-encode images or PDFs — it will exceed the context window.

Get the valid values for the Gewerbeanmeldung enum fields (value → label).

Get list of attachments with optional filters. Args: file_name: Filter by file name (case insensitive partial match) linked: Filter by whether attachment is linked to transactions attachment_type: Filter by attachment type (invoice, receipt, contract, other) description: Filter by description (case insensitive partial match) brand_name: Filter by brand name (case insensitive partial match) Returns: List of attachments matching the filters. Use downloadUrl for direct temporary file download links.

Create a new attachment with a file. Args: transactions: List of transaction IDs to link attachment_type: Type of attachment (invoice, receipt) amount: Amount related to attachment amount_exchanged: Exchanged amount in different currency attachment_number: Unique number for attachment brand_name: Brand name associated with attachment currency: Currency of amount (default EUR) currency_exchanged: Exchanged currency (default EUR) description: Description of attachment supplier_country: Country of supplier (DE, INSIDE_EU, OUTSIDE_EU) value_date: Date of value vat_sum_amount: VAT sum amount vat_sum_amount_exchanged: Exchanged VAT sum amount vat_rate: VAT rate percentage sale_type: Type of sale additional_metadata: Additional metadata for attachment How to provide the file (pick one): 1. file_url — best if the file has a public HTTP(S) URL 2. file_ref — call request_file_upload first to get an upload link, ask the user to open it in their browser and drop the file, then pass the file_ref here 3. file_content_base64 — ONLY for tiny files under 50 KB NEVER base64-encode images, PDFs, or scans — they will blow up the context window. Use file_url or request_file_upload instead.

Link a transaction to an attachment. Args: attachment_id: ID of the attachment transaction_id: ID of the transaction to link Returns: Response from the link transaction request

Delete an attachment — e.g. an orphan receipt/invoice with no linked transaction (a stale self-statement left behind after the real invoice was attached). Retention-aware: Norman keeps documents under GoBD retention. A retained document returns a 409 whose `detail.requiresConfirmation` is true (with a `retentionUntil` date); re-call with `confirm=true` to override. Only call once the user has confirmed the attachment should be removed. Args: attachment_id: ID of the attachment to delete confirm: set true to override the legal-retention guard on a retained document Returns: Confirmation of deletion, or the 409 retention warning if confirm is not set

Download an attachment and return it as an inline image. Works for image attachments (PNG, JPEG, GIF, WebP). For PDFs and other non-image files, returns the download URL instead.

Search the FULL SKR chart of accounts (SKR03 or SKR04) by account code. ⚠️ SME ONLY — this tool works exclusively for GmbH/UG companies with a DATEV chart of accounts. For freelance accounts use 'categorize_transaction'. Searches the complete catalog (~1000+ entries), NOT just the company's provisioned categories. Use when you know the account number or its prefix. Returns matching entries with accountNumber, nameDe, nameEn.

Use AI to find the best matching SKR categories by name or description. ⚠️ SME ONLY — this tool works exclusively for GmbH/UG companies with a DATEV chart of accounts (SKR03/SKR04). For freelance accounts use 'categorize_transaction' which has its own AI-powered category detection. Sends the query to OpenAI along with the full SKR catalog as context, so it can semantically match even vague or partial descriptions. Returns up to 5 best matching entries with accountNumber, nameDe, nameEn. NOTE: This calls OpenAI — prefer search_skr_by_code when you have a code.

Create a new custom company category for the active SME company. ⚠️ SME ONLY — only works for GmbH/UG companies with a DATEV chart of accounts. Not applicable to freelance accounts. Use search_skr_by_code or suggest_skr_category first to find the right account number from the full SKR catalog, then create the category here.

Section 5 (financials): capital, start of activity, fiscal year, expected profits.

Hide or unhide SME company categories in bulk. ⚠️ SME ONLY — GmbH/UG companies with a DATEV chart of accounts. Hidden categories disappear from the category pickers in the app and from the candidate list the AI categorizer picks from. Nothing is deleted: transactions already booked on a hidden category keep it (the result reports transactionsCount / itemsCount per row), and unhiding restores the row exactly as it was. The main use: a company whose chart was provisioned twice and now shows both SKR03 and SKR04 accounts. Hide the chart it does not use. Selectors combine with AND and at least one is required. A non-zero summary.skippedCustom means the filter passed over hand-made accounts — rerun with include_custom=true if the user meant those too. Preview with dry_run=true and tell the user what would be hidden before doing it for real — this changes what they can book on.

Get detailed information about the user's company.

Get the current balance of the company. Returns: Company balance information

Update company information. For SME companies you can also set chart_of_accounts, DATEV advisor/client numbers.

List SME company categories from the DATEV chart of accounts (SKR03/SKR04). These categories are specific to the company and are used for GmbH/UG bookkeeping. Each category has a code (e.g. '4200'), name, cashflow type, and sourceTemplate — the chart of accounts it was provisioned from ('' for hand-made ones). A company showing both SKR03 and SKR04 accounts can be cleaned up with set_company_categories_visibility. Hidden categories are omitted unless include_inactive=true.

List available Chart of Accounts templates (e.g. SKR03, SKR04) that can be assigned to an SME company.

Trigger a DATEV export for the company's transactions in the specified period. Generates a ZIP containing a DATEV EXTF CSV, a human-readable statement CSV, and optionally all attached documents. Only finalized transactions are included.

Create a new invoice. Ask for additional information if needed, for example: - If the client is not found, ask for the client details and create a new client if necessary. - If pyament reminder should be sent, ask for the reminder settings. - If the invoice type is GOODS, ask for the delivery date. - If the invoice type is SERVICES, ask for the service start and end dates. - If the invoice should be sent to the client, ask for the email data. Args: client_id: ID of the client for the invoice items: List of invoice items, each containing name, quantity, rate, vatRate and total. Example: [{"name": "Software Development", "quantity": 3, "rate": 30000, "vatRate": 19, "total": 1071}] // VAT rates might be 0, 7, 19. By default it's 19. Rate and total are in cents. invoice_number: Optional invoice number (will be auto-generated if not provided) issued: Issue date in YYYY-MM-DD format due_to: Due date in YYYY-MM-DD format currency: Invoice currency (EUR, USD), by default it's EUR payment_terms: Payment terms text notes: Additional notes language: Invoice language (en, de) invoice_type: Type of invoice (SERVICES, GOODS) is_vat_included: Whether prices include VAT bank_name: Name of the bank (gets from company details if exists) iban: IBAN for payments (gets from company details if exists) bic: BIC/SWIFT code (gets from company details if exists) create_qr: Whether to create payment QR code (only if BIC and IBAN provided) color_schema: Invoice style color (hex code) font: Invoice font (e.g. "Plus Jakarta Sans", "Inter") is_to_send: Whether to send invoice automatically to client mailing_data: Email data if is_to_send is True. Example: { "emailSubject": "Invoice No.{invoice_number} for {client_name}", "emailBody": "Dear {client_name},...", "customClientEmail": "client@example.com" // email to send the invoice to, if not provided, it will be sent to the client email address } settings_on_overdue: Configuration for overdue notifications. Example: { "isToAutosendNotification": true, // whether to send notification automatically "customEmailSubject": "Reminder: Invoice {invoice_number} is overdue", // custom email subject "customEmailBody": "Dear {client_name},...", // custom email body "notifyAfterDays": [1, 3], // days to notify after the due date "notifyInParticularDays": [] // days to notify in particular dates [2025-05-23", "2025-05-24"] } service_start_date: Service period start date (YYYY-MM-DD) by default it's today, should be provided if invoice_type is SERVICES service_end_date: Service period end date (YYYY-MM-DD) by default it's one month from today, should be provided if invoice_type is SERVICES delivery_date: Delivery date for goods (YYYY-MM-DD) by default it's today, should be provided if invoice_type is GOODS Returns: Information about the created invoice. Use downloadUrl for a direct temporary PDF download link (valid for 1 hour).

Create a recurring invoice that will automatically generate new invoices based on specified frequency. Useful for contracts or services that bill on a regular basis. Always ask for reccurring configuration, for example: - How often to generate invoices (weekly, monthly) - Number of units for frequency (e.g. 1 for monthly = every month, 2 = every 2 months) - Start date - End date - End invoice count (optional) Ask for additional information if needed, for example: - If the client is not found, ask for the client details and create a new client if necessary. - If the invoice number is not provided, ask for it. - If the due date is not provided, ask for it. - If the payment terms are not provided, ask for it. - If the bank details are not provided, ask for it. Args: client_id: ID of the client for the invoice items: List of invoice items, each containing name, quantity, rate, vatRate and total frequency_type: How often to generate invoices ("weekly", "monthly") frequency_unit: Number of units for frequency (e.g. 1 for monthly = every month, 2 = every 2 months) starts_from_date: Date to start generating invoices from (YYYY-MM-DD) ends_on_date: Optional end date for recurring invoices (YYYY-MM-DD). Either ends_on_date or ends_on_invoice_count should be provided. ends_on_invoice_count: Optional number of invoices to generate before stopping. Either ends_on_date or ends_on_invoice_count should be provided. invoice_number: Base invoice number (will be auto-generated if not provided) issued: Issue date in YYYY-MM-DD format due_to: Due date in YYYY-MM-DD format currency: Invoice currency (EUR, USD), by default it's EUR payment_terms: Payment terms text notes: Additional notes language: Invoice language (en, de) invoice_type: Type of invoice (SERVICES, GOODS) is_vat_included: Whether prices include VAT bank_name: Name of the bank iban: IBAN for payments bic: BIC/SWIFT code create_qr: Whether to create payment QR code color_schema: Invoice style color (hex code) font: Invoice font (e.g. "Plus Jakarta Sans", "Inter") is_to_send: Whether to send invoices automatically to client settings_on_overdue: Configuration for overdue notifications service_start_date: Service period start date (for SERVICES type) service_end_date: Service period end date (for SERVICES type) delivery_date: Delivery date (for GOODS type) Returns: Information about the created recurring invoice. Use downloadUrl for a direct temporary PDF download link (valid for 1 hour).

Get detailed information about a specific invoice. Args: invoice_id: ID of the invoice to retrieve Returns: Detailed invoice information

Send an invoice via email. Args: invoice_id: ID of the invoice to send subject: Email subject line body: Email body content additional_emails: List of additional email addresses to send to is_send_to_company: Whether to send the copy to the company email (Owner) custom_client_email: Custom email address for the client (By default the email address of the client is used if it is set) Returns: Response from the send invoice request

The FINAL step: hand the user over to the Norman app to review and submit. The e-filing to the Finanzamt (via ELSTER) is a binding legal act, so it is done in the app only: the user opens the link, sees the rendered ELSTER preview of every answer and presses Submit themselves. Returns the link plus the current completeness state — if `readyToSubmit` is false, finish the `missing` fields first.

Send an overdue payment reminder for an invoice via email. Args: invoice_id: ID of the invoice to send reminder for subject: Email subject line body: Email body content additional_emails: List of additional email addresses to send to is_send_to_company: Whether to send the copy to the company email (Owner) custom_client_email: Custom email address for the client (By default the email address of the client is used if it is set) Returns: Response from the send overdue reminder request

Link a transaction to an invoice. Args: invoice_id: ID of the invoice transaction_id: ID of the transaction to link Returns: Response from the link transaction request

Get the e-invoice XML for a specific invoice. Args: invoice_id: ID of the invoice to get XML for Returns: E-invoice XML data

List invoices with optional filtering. Args: status: Filter by invoice status (draft, pending, sent, paid, overdue, uncollectible) name: Filter by invoice (client) name from_date: Filter invoices created after this date (YYYY-MM-DD) to_date: Filter invoices created before this date (YYYY-MM-DD) limit: Maximum number of invoices to return (default 100) Returns: List of invoices matching the criteria

Get a visual preview of an invoice. Returns an inline JPEG image of the first page of the invoice PDF, rendered directly in clients that support MCP ImageContent. Also includes a downloadUrl for the full PDF.

Get an aggregated financial health snapshot for a client company. Combines company details, balance, transaction stats, missing receipts, outstanding invoices, and tax report status into a single overview. Designed for tax advisors managing multiple client companies. Returns: A structured overview with company info, financial summary, document completeness, and tax compliance status.

List all transactions without receipts for a client company, grouped by month and category with amounts. Useful for tax advisors to know what documents to request from the client. Returns: Summary with total missing count, grouped by month, and a flat list of the top missing transactions ordered by amount.

Check the tax compliance status for a client company. Identifies which tax reports are due, overdue, or unfiled, and flags any validation issues. Returns: Compliance summary with report status breakdown and action items.

Send document request reminders to a client for multiple transactions at once. Each transaction triggers an email to the company owner asking them to upload the missing receipt or invoice. Returns: Summary of which pings succeeded and which failed.

List all client companies managed by the authenticated tax advisor. Each entry includes the company ID, name, account type, transaction count, and number of transactions missing documents. Use the returned company IDs with switch_company to change the active company, or pass them to other tax advisor tools like get_client_overview.

Switch the active company context. All subsequent tool calls will operate on the selected company. Tax advisors can use this to switch between client companies; regular users can switch if they own multiple companies.

Section 6 (VAT & bank): revenue forecast, Kleinunternehmer choice, taxation method, VAT ID and the refund bank account.

Create a new offer/quote. Args: client_id: ID of the client for the offer items: List of offer items. Example: [{"name": "Software Development", "quantity": 3, "rate": 30000, "vatRate": 19}] VAT rates might be 0, 7, 19. Rate is in cents. offer_number: Optional offer number (will be auto-generated if not provided) issued: Issue date in YYYY-MM-DD format valid_until: Offer validity date in YYYY-MM-DD format (defaults to 30 days from today) currency: Offer currency (EUR, USD), by default it's EUR payment_terms: Payment terms text notes: Additional notes language: Offer language (en, de) invoice_type: Type of offer (SERVICES, GOODS) is_vat_included: Whether prices include VAT bank_name: Name of the bank iban: IBAN for payments bic: BIC/SWIFT code create_qr: Whether to create payment QR code (only if BIC and IBAN provided) color_schema: Offer style color (hex code) font: Offer font (e.g. "Plus Jakarta Sans", "Inter") is_to_send: Whether to send the offer automatically to client mailing_data: Email data if is_to_send is True service_start_date: Service period start date (YYYY-MM-DD) service_end_date: Service period end date (YYYY-MM-DD) delivery_date: Delivery date for goods (YYYY-MM-DD) Returns: Information about the created offer. Use downloadUrl for a direct temporary PDF download link when available.

List offers/quotes with optional filtering. Args: status: Filter by offer status (draft, pending, saved, sent, approved) name: Filter by client name from_date: Filter offers created after this date (YYYY-MM-DD) to_date: Filter offers created before this date (YYYY-MM-DD) limit: Maximum number of offers to return (default 100) Returns: List of offers matching the criteria

Get detailed information about a specific offer/quote. Args: offer_id: ID of the offer to retrieve Returns: Detailed offer information

Send an offer/quote via email. Args: offer_id: ID of the offer to send subject: Email subject line body: Email body content additional_emails: List of additional email addresses to send to is_send_to_company: Whether to send a copy to the company email custom_client_email: Custom client email address Returns: Response from the send offer request

Convert an offer/quote into an invoice. The backend creates a new invoice from the quote data and removes the original quote. Args: offer_id: ID of the offer to convert Returns: Newly created invoice information

Get the user's corporate tax registration (Fragebogen), if any. Call this FIRST. A "not found" response means there is none — offer to start one with create_corporate_tax_registration. Otherwise resume from `sections.missing`. `status` == 'submitted' means it was already e-filed; `reportUrl` carries the transmission protocol PDF.

Get the valid values for the corporate Fragebogen enum fields (value → label).

Start the corporate Fragebogen. 400 if an active one already exists (use get_corporate_tax_registration). When linked to an incorporation, the company data, notary date, capital, shareholders and managing directors are prefilled — review `sections.missing` afterwards and only ask the user for what is still open.

Section 1 (company): name, seat, addresses, contact, activity and tax office.

Section 2 (registration): notary date and Handelsregister state.

Sections 3+4 (people): managing directors and shareholders, replace-all semantics.

Start a Gewerbeanmeldung. 400 if one already exists (use get_gewerbe_registration). If linked to an incorporation, the company, address, activity and managing directors are pre-filled. For self-employed users the answers from their tax-registration Fragebogen are carried over automatically.

Section 1 (basics): when the trade starts and whether it's a head or branch office.

Section 2 (business): legal form, name, Betriebsstätte address, activity, licence, public-sector participation and employees. `commercialRegisterNumber` is required for legal entities (GmbH/UG/AG/…); licence/employee details only when their flag is true.

Section 3 (owner / authorized representative): personal data, address and main-vs-secondary occupation. Set `ownerAddressSameAsBusiness` true when the home is the business address; otherwise provide the residence fields.

Reformulate a rough trade activity into precise, Gewerbeamt-ready wording. Returns {"suggestion": ...} — a faithful same-language rewrite (concrete activity, no catch-all phrases, nothing invented). Show it to the user; apply it via update_gewerbe_business(activity_description=...) only if they accept.

Generate the pre-filled GewA 1 PDF. 400 + `missing` if a section is incomplete. Get the user's explicit confirmation first. The PDF is a template for self-submission to the Gewerbeamt (not legal advice); it carries a blank signature line for the user to sign on paper. Returns the download descriptor; follow with get_gewerbe_trade_office to tell them where to submit.

Return the first page of the generated GewA 1 as an image for the user to review.

Resolve the responsible trade office (Gewerbeamt) for the business address. Returns {"office": {...}} or {"office": null} — if null, tell the user to search for "<their city> Gewerbeamt" to find where to submit.

Get a list of all vendors (suppliers) for the company. Returns: List of vendors with their details

Get detailed information about a specific vendor. Args: vendor_id: ID of the vendor to retrieve Returns: Detailed vendor information

Create a new vendor (supplier). Args: name: Vendor name or business name iban: Vendor bank account IBAN bic: Vendor bank BIC/SWIFT email: Vendor email address phone: Vendor phone number address: Vendor physical address country: Vendor country code (e.g. "DE") vat_number: Vendor VAT number Returns: Newly created vendor record

Update an existing vendor. Only the fields you pass are changed. Args: vendor_id: ID of the vendor to update name: Updated vendor name iban: Updated IBAN bic: Updated BIC/SWIFT email: Updated email address phone: Updated phone number address: Updated physical address country: Updated country code (e.g. "DE") vat_number: Updated VAT number Returns: Updated vendor record

Delete a vendor. Args: vendor_id: ID of the vendor to delete Returns: Confirmation of deletion