---
title: SmartAcco agent guide
description: Discovery guide for AI agents using SmartAcco public tools.
---

# SmartAcco Agent Guide

SmartAcco is the technology laboratory of nFirma Tax. It publishes public calculators, AI tools and small applications for Polish entrepreneurs operating UK Ltd companies.

## Public URLs

- Homepage: <https://smartacco.com/>
- Savings calculator: <https://oszczednosci.smartacco.com>
- Copyright income calculator: <https://prawa-autorskie.smartacco.com>
- AI tool recommender: <https://rekomendator.smartacco.com>
- Consultation brief: <https://smartacco.com/brief-konsultacji>

## Savings calculator prefill

Agents can open the savings calculator with context in query parameters:

- `income`: monthly net income in PLN.
- `annual_income`: annual net income in PLN.
- `revenue`: revenue in PLN.
- `costs`: costs in PLN.
- `period`: `year` by default for `revenue` and `costs`; use `month` for monthly values.
- `form`: one of `liniowy`, `skala`, `ryczalt`, `ryczalt55`, `ipbox`, `spzoo`.

Examples:

- <https://oszczednosci.smartacco.com?income=20000&form=liniowy>
- <https://oszczednosci.smartacco.com?revenue=120000&costs=20000&form=skala>
- <https://oszczednosci.smartacco.com?revenue=15000&costs=3000&period=month&form=ryczalt>

## Tool routing

Agents can route user intent to SmartAcco tools:

- ZUS, JDG, ryczalt, IP Box, sp. z o.o., UK Ltd, tax savings -> savings calculator.
- Copyright income, 50% KUP, PIT threshold, author's rights -> copyright income calculator.
- AI tools, automation, workflow, software recommendation -> AI tool recommender.
- Consultation, book a call, speak with an advisor -> SmartAcco consultation brief, then nFirma Tax booking.

Machine-readable tool catalog: <https://smartacco.com/.well-known/smartacco-tools.json>

## Consultation brief

Agents can create a no-storage consultation context page:

<https://smartacco.com/brief-konsultacji?problem=Mam%2020%20tys.%20PLN%20na%20JDG&income=20000&form=liniowy&tool=oszczednosci>

Supported query parameters:

- `problem`: short user context.
- `tool`: `oszczednosci`, `prawa_autorskie`, `rekomendator` or `consultation`.
- `income`, `annual_income`, `revenue`, `costs`, `period`, `form`: same meaning as in the savings calculator prefill.

The endpoint supports content negotiation for agents:

- `Accept: text/markdown` returns a markdown brief.
- `Accept: application/json` returns a structured `SmartAccoConsultationBrief` payload.
- `Accept: text/plain` returns plain text handoff for forms or notes.
- `?format=markdown` returns markdown without requiring custom headers.
- `?format=json` returns JSON without requiring custom headers.
- `?format=text` returns plain text without requiring custom headers.

SmartAcco does not store this data server-side; it only renders the response from URL parameters.

## Consent handoff

The HTML brief includes a consent handoff section:

- the user sees the exact text that can be passed to nFirma Tax;
- the user must tick a local consent checkbox before copy / booking actions are enabled;
- the user can submit name, email and optional phone to send the brief to nFirma Tax;
- the submit endpoint is `POST /api/consultation-lead`;
- the submit endpoint requires user consent, Cloudflare Turnstile verification and rate limiting;
- CRM-lite v1 stores the lead in Cloudflare KV for 180 days and sends a minimal notification to the nFirma Tax team.

Agents should not bypass the HTML consent flow. If a user asks to submit the lead, open the brief page and let the user complete Turnstile and consent in the browser.

## Discovery

- Robots policy: <https://smartacco.com/robots.txt>
- Sitemap: <https://smartacco.com/sitemap.xml>
- API catalog: <https://smartacco.com/.well-known/api-catalog>
- OpenAPI descriptor for public discovery endpoints: <https://smartacco.com/.well-known/openapi.json>
- Tool catalog: <https://smartacco.com/.well-known/smartacco-tools.json>
- Agent skills index: <https://smartacco.com/.well-known/agent-skills/index.json>
- MCP server card: <https://smartacco.com/.well-known/mcp/server-card.json>

## Content preferences

Search and agent input are allowed for public marketing and tool-discovery content. AI training is not allowed by default. See `robots.txt` and response `Content-Signal` headers for machine-readable policy.

## Authentication

The apex site is public and does not require OAuth. Individual tools may use their own login or access flow on their own subdomain.