TypeScript SDK for the Austrian FinanzOnline (BMF) SOAP web services — session, abfrage-datenuebermittlung, and unified fileupload submission with per-year typed payloads.
Strong domain-specific tool design with clear, detailed descriptions and well-structured schemas. All 7 tools have explicit input schemas with typed parameters and comprehensive descriptions (avg 180 chars, well within 10-1024 baseline). Tool names follow verb_noun convention (list_, describe_, build_, validate_, pipeline, abfrage, upload). Schemas use proper JSON Schema with type declarations and parameter descriptions. However, output schemas are not documented in the tool definitions themselves, LLMs must infer response structure from descriptions. Error handling guidance is present in descriptions but not formalized as structured error types. No tool annotations (readOnlyHint/destructiveHint) despite clear risk classifications in metadata.
Run a FinanzOnline Abfrage-Datenübermittlung query. Reads BMF data submitted by third parties (Lohnzettel from employers, Sonderausgaben from charities, etc.) for a given FASTNR and tax year.
Build a BMF-conformant XML payload from a typed JSON body. **Recommended workflow: call `describe_art` first to fetch the body's JSON Schema, then construct your body to match.** Each art's body shape is enforced by Zod at runtime — invalid inputs return a structured ValidationError with field-level issues grouped by section (`grouped.sections[].section`). Year/effective-date-versioned arts (L1, JAHR_ERKL, U30, KA1, VPDGD) require a version; others default to 'current'.
Return a JSON Schema (Draft-7) describing the typed body shape this package expects for `build_xml` of a given art × version. Call this first to learn the field names, types, and constraints — feed the returned schema into your prompt or validator before constructing a body.
List the 36 BMF FinanzOnline upload art codes plus a per-art map of typed-builder versions ('current', '2025', 'ab_2022', 'v2_0', etc.). Use the version key with build_xml / validate_xml to target a specific schema.
Build → validate → (optionally) submit a typed JSON body in a single call. **Recommended workflow: call `describe_art` once first to learn the body shape, then drive `pipeline` for every subsequent filing.** Each stage's status surfaces independently in the response: `build.ok`, `validate.ok`, `submit.skipped|parsed`. Saves 2-3 round-trips for agents that already know the body shape. Pass `submit=true` (and optionally `uebermittlung`) to also file; otherwise stops after validate.
Output schemas not documented in tool definitions. LLMs cannot plan downstream calls or extract fields without inferring response structure from descriptions alone.
Tool annotations missing. Despite clear risk classifications (READ_ONLY vs WRITE), tools lack readOnlyHint and destructiveHint annotations. Agents cannot distinguish safe from destructive operations without parsing descriptions.
Error handling not formalized. Descriptions mention ValidationError and structured failures, but no explicit error response schema or recovery guidance (e.g., 'If validation fails, call describe_art to verify body shape').
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 65 | 2026-07-28+ | v2 |
Submit a pre-built XML payload via the BMF fileupload service. Defaults to Test (uebermittlung='T'); pass 'P' only when filing for real. Returns the parsed BMF protocol response (OK / NOK / TWOK).
Validate an XML payload against the bundled BMF XSD for the given art. Returns ok=true on success or a structured failure (xmllint stderr, xsd-incompatible, missing-xmllint, etc.).
Credentials injected via environment variables (FON_TID, FON_BENID, FON_PIN, FON_HERSTELLERID) but no explicit documentation of required permissions or scope declarations in tool definitions.
No pagination or result-limiting guidance. list_arts returns 36 items (manageable), but no documentation of max result sizes or pagination patterns for future extensibility.