kubik-tools

Calculates chargeable (billable) weight -- frachtpflichtiges Gewicht, Frachtgewicht -- for a freight shipment (Stückgut or Sammelgut) from a list of cargo pieces, for one of four transport modes. Answers questions like "wie viel wiegt die Sendung frachtpflichtig" or "was ist das Volumengewicht". For each mode, chargeable weight is the greater of the actual (scale) weight and the volumetric weight (Volumengewicht), where volumetric weight is derived from total volume using a mode-specific default divisor (overridable via volumetric_divisor): - air (Luftfracht): volume_cm3 / 6000 (IATA standard, 167 kg/m3) - courier: volume_cm3 / 5000 (common express-carrier convention, e.g. DHL/FedEx/UPS) - road: volume_m3 * 333 (simple volumetric "1:3" convention; does not model Lademeter/LDM-based road pricing -- for loading-metre, Stellplätze, or vehicle-fit questions, use calculate_loading_metres and check_truck_fit instead, both on this server) - sea_lcl (Seefracht): volume_m3 * 1000 (W/M -- weight or measurement, 1 revenue tonne per m3) Worked example: 2 pieces, 60x40x50cm, 45 kg each, air mode -> total actual weight 90 kg, total volume 0.24 m3, volumetric weight 40 kg (240,000 cm3 / 6000) -> chargeable weight 90 kg (actual weight governs, since it exceeds the volumetric weight). Rounding: air and courier chargeable/volumetric weight round UP to the nearest 0.5 kg (chargeable_weight_raw_kg gives the unrounded value, chargeable_weight_kg the rounded one). Road and sea_lcl are not rounded up, just reported to 1 decimal place. Edge cases: missing or invalid mode, more than 100 pieces, or any non-positive dimension/weight/quantity returns a clear, structured explanation rather than an error stack -- never a guessed default mode or divisor. Returns total actual weight, total volume, volumetric weight, raw and rounded chargeable weight, which one governs, the divisor used, and a one-line human-readable summary.

{
  "type": "object",
  "properties": {
    "pieces": {
      "description": "List of cargo pieces (up to 100 line items, required, non-empty). Use quantity to combine identical pieces rather than repeating rows.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "quantity": {
            "description": "Number of identical pieces in this line. Must be a positive number.",
            "type": "number"
          },
          "length_cm": {
            "description": "Length of one piece, in centimeters (Länge in cm). Must be a positive number.",
            "type": "number"
          },
          "width_cm": {
            "description": "Width of one piece, in centimeters (Breite in cm). Must be a positive number.",
            "type": "number"
          },
          "height_cm": {
            "description": "Height of one piece, in centimeters (Höhe in cm). Must be a positive number.",
            "type": "number"
          },
          "weight_kg_per_piece": {
            "description": "Actual (scale) weight of one piece, in kilograms (Gewicht in kg). Must be a positive number.",
            "type": "number"
          }
        }
      }
    },
    "mode": {
      "description": "Transport mode (required): one of \"air\" (Luftfracht), \"road\", \"sea_lcl\" (Seefracht), \"courier\". Selects the default volumetric divisor: air=6000 cm³/kg (IATA), courier=5000 cm³/kg, road=333 kg/m³ (simple volumetric convention — for loading-metre/Lademeter/LDM and vehicle-fit questions, use calculate_loading_metres and check_truck_fit instead, both on this server), sea_lcl=1000 kg/m³ (W/M).",
      "type": "string"
    },
    "volumetric_divisor": {
      "description": "Optional positive override of the mode's default divisor. For air/courier this is cm³ per kg (divided into volume); for road/sea_lcl this is kg per m³ (multiplied by volume).",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Resolves an ordered quantity of a Library article into concrete packed units (boxes/pallets), using that article's own logged packing history -- never a generic guess. Check resolution_status first: "resolved" means units/tier are a real answer, safe to use directly. "ambiguous" means the article has more than one viable packaging family (e.g. logged both as pallets and as crates) with meaningfully different pack counts -- units and tier are both null, and alternatives lists every viable option with no default among them. When resolution_status is "ambiguous", do not select an alternative autonomously -- present the options to the user and ask which packaging family they mean; do not guess based on which one appears first. "not_found" means the article has no packed-form data logged at all -- there is nothing to resolve, alternatives is absent, and units/tier are null. needs_confirmation (boolean) is kept only for backward compatibility with callers written before resolution_status existed -- new integrations should check resolution_status. When resolution_status is "resolved", tier is one of: "observed" (an exact match against a real logged pack), "estimated" (interpolated between two real logged points), or "verify" (extrapolated beyond the highest -- or below the lowest -- quantity ever actually logged for this article; still returns a real number, but flagged as needing a human's eyes before it's trusted). Does not resolve prepack-table or consolidation-group quantities -- those use the same tier engine but a different lookup key (a table/group id, not a free-text article search) and are not covered by this tool. Requires an MCP API key (Authorization: Bearer <key>) issued for a kubik.tools team. Looks the article up by article number or name within that team's own Library -- never across teams.

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Your team's kubik.tools MCP API key (kubik_mcp_...). Required."
    },
    "article_query": {
      "type": "string",
      "description": "The article number or name to search for in the Library, e.g. 'MLB1001' or 'rim holder'."
    },
    "quantity": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "The ordered quantity to resolve, in whole units of the article. Must be a positive number."
    }
  },
  "required": [
    "api_key",
    "article_query",
    "quantity"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Resolves an ordered quantity of a CLASS of goods into concrete prepack units (boxes/cartons), using that class's own logged prepack table -- a class-level lookup (e.g. "small metal fittings"), not a single article. Use resolve_quantities instead when you have a specific article number/name. Check resolution_status first: "resolved" means units/tier are a real answer, safe to use directly. "not_found" means no prepack table matched the search text, or the matched table has no threshold rules logged -- units/tier are both null. Prepack tables never produce "ambiguous" results (unlike resolve_quantities) -- a table either resolves or it doesn't, there is no packaging-family choice to make. When resolution_status is "resolved", tier is one of: "observed" (an exact match against a real logged threshold), "estimated" (interpolated between two real logged thresholds), or "verify" (extrapolated beyond the highest -- or below the lowest -- threshold ever actually logged for this table; still returns a real number, but flagged as needing a human's eyes before it's trusted). Requires an MCP API key (Authorization: Bearer <key>) issued for a kubik.tools team. Looks the prepack table up by its own article_class text within that team's own Library -- never across teams.

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Your team's kubik.tools MCP API key (kubik_mcp_...). Required."
    },
    "article_class_query": {
      "type": "string",
      "description": "Free-text search over the prepack table's own article_class label, e.g. 'small metal fittings' or 'cable ties'."
    },
    "quantity": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "The ordered quantity to resolve, in whole units of the class. Must be a positive number."
    }
  },
  "required": [
    "api_key",
    "article_class_query",
    "quantity"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Searches your team's kubik.tools Library for article profiles by article number or name (case-insensitive substring match). Returns up to 10 matches: id, article_number, name, supplier. Leave query empty (or a single common substring) to browse -- this returns whatever matches, sorted however the underlying table naturally orders (no ranking beyond "matched or not"), never a full unfiltered dump beyond the 10-result cap. Use resolve_quantities once you've found the article you want to resolve a quantity against; use this tool first to find its exact article_number/id if you only have a rough description. Requires an MCP API key (Authorization: Bearer <key>) issued for a kubik.tools team. Only ever returns that team's own Library -- never across teams.

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Your team's kubik.tools MCP API key (kubik_mcp_...). Required."
    },
    "query": {
      "default": "",
      "description": "Article number or name substring to search for, e.g. 'MLB1001' or 'rim holder'. Leave empty to browse the first 10 articles in the Library.",
      "type": "string"
    }
  },
  "required": [
    "api_key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Creates a new article in your team's kubik.tools Library -- team-scoped from creation, visible to the whole team immediately (not a personal draft). Two-step by design, never a silent write: call once WITHOUT confirm to get a preview of exactly what would be created (including a check for an existing article that looks like a likely duplicate); call again with confirm=true and the preview_id from the first response to actually create it. A confirmed creation can be undone within 15 minutes via undo_change -- after that, edit or delete it directly in the app. On the confirm call, only api_key, confirm, and preview_id are actually read -- every other field is required/optional per the schema for shape-consistency but ignored if resupplied, since the values captured during the preview call are what gets created; to change any of them, call again without confirm for a fresh preview. Do not use this to log a real packing observation for an article that already exists -- use log_pack_observation instead; this tool only creates the article record itself, never packing data. Do not skip the unconfirmed preview call even if you are confident there is no duplicate -- the duplicate check only runs on that first call, and confirm=true without a fresh preview_id will be rejected. Required: name, supplier. Optional: article_number, hs_code (exactly 8 digits if given), description_de, description_en.

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Your team's kubik.tools MCP API key (kubik_mcp_...). Required."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Article name, e.g. 'Rotor hub casting'. Required."
    },
    "supplier": {
      "type": "string",
      "minLength": 1,
      "description": "Supplier name. Required."
    },
    "article_number": {
      "description": "Supplier's own article/SKU number, if known.",
      "type": "string"
    },
    "hs_code": {
      "description": "HS/tariff code, exactly 8 digits. Format-only check -- not verified against a real tariff database.",
      "type": "string"
    },
    "description_de": {
      "type": "string"
    },
    "description_en": {
      "type": "string"
    },
    "confirm": {
      "description": "Set true, with preview_id, to actually create the article after reviewing the preview. Omit or false for a dry-run preview only.",
      "type": "boolean"
    },
    "preview_id": {
      "description": "The preview_id returned by the first (unconfirmed) call. Required when confirm=true.",
      "type": "string"
    }
  },
  "required": [
    "api_key",
    "name",
    "supplier"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Logs a real, observed consolidation pack -- "these articles, at these quantities, actually packed onto N pallets at these dims/weight" -- against an existing consolidation group in your team's Library. This is ground truth: it becomes a new data point resolve_quantities and the app's own resolve flow learn from (PRINCIPLES.md P-13). Two-step by design: call once WITHOUT confirm to preview exactly what would be logged; call again with confirm=true and the preview_id to actually log it. A confirmed log can be undone within 15 minutes via undo_change -- after that it's permanent (append-only ground truth, by design -- see PRINCIPLES.md P-17/P-18 for why). On the confirm call, only api_key, confirm, and preview_id are actually read -- every other field is required by the schema for shape-consistency but ignored if resupplied, since the values captured during the preview call are what gets logged; to change any of them, call again without confirm for a fresh preview. Do not use this for a single article's own packing history outside a consolidation group -- that data comes from the app's own data entry, not this tool. Do not use this to correct a mistaken past observation after the 15-minute undo window -- log a new, correct observation instead; past ones are never edited. Requires an EXISTING consolidation_groups id -- this tool cannot create a new consolidation group. Requires an existing consolidation_groups id (from the app's Consolidation Groups screen) and each member article's number (resolved to its profile automatically).

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Your team's kubik.tools MCP API key (kubik_mcp_...). Required."
    },
    "consolidation_group_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The id of an existing consolidation group in your team's Library. Required."
    },
    "member_quantities": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "article_number": {
            "type": "string",
            "minLength": 1,
            "description": "The article's number, as it appears in the Library."
          },
          "qty": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Quantity of this article in the observed pack."
          }
        },
        "required": [
          "article_number",
          "qty"
        ]
      },
      "description": "The articles and quantities actually packed together, e.g. [{article_number: 'MLB1001', qty: 3}]."
    },
    "pallet_count": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Number of pallets this pack used."
    },
    "length_cm": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "width_cm": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "height_cm": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "weight_kg": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Total gross weight, in kg."
    },
    "confirm": {
      "description": "Set true, with preview_id, to actually log the observation after reviewing the preview. Omit or false for a dry-run preview only.",
      "type": "boolean"
    },
    "preview_id": {
      "description": "The preview_id returned by the first (unconfirmed) call. Required when confirm=true.",
      "type": "string"
    }
  },
  "required": [
    "api_key",
    "consolidation_group_id",
    "member_quantities",
    "pallet_count",
    "length_cm",
    "width_cm",
    "height_cm",
    "weight_kg"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Lists the real, observed consolidation packs logged against a consolidation group in your team's Library -- "these articles, at these quantities, actually packed onto N pallets at these dims/weight," the same ground-truth data resolve_quantities/resolve_prepack_quantities and the app's own resolve flow learn from (PRINCIPLES.md P-13). Use this to see what's already been logged for a group before deciding whether a new observation (log_pack_observation) is needed, or to review a group's own observation history. Each observation's member_quantities are resolved to article_number/name for readability -- never a bare internal id. Returns an empty observations array (not an error) for a group that exists but has no observations logged yet -- a real, valid state, not a failure. Requires an MCP API key (Authorization: Bearer <key>) issued for a kubik.tools team. Looks the consolidation group up by its own name text within that team's own Library -- never across teams.

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Your team's kubik.tools MCP API key (kubik_mcp_...). Required."
    },
    "group_name_query": {
      "type": "string",
      "description": "Free-text search over the consolidation group's own name, e.g. 'pallet mix A' or 'mixed cartons'."
    }
  },
  "required": [
    "api_key",
    "group_name_query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Undoes a create_article_profile or log_pack_observation call, but only within 15 minutes of when it was confirmed, and only if nothing else now depends on it. For article_profiles: refuses if any packed_forms, consolidation_group_members, or edit-history rows now reference the article (edit it or delete it manually in the app instead of undoing). For consolidation_pack_observations: append-only ground truth past the 15-minute window, by design (PRINCIPLES.md P-17/P-18) -- undo only exists for a mistake caught immediately after logging it, never as a general edit/delete capability.

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Your team's kubik.tools MCP API key (kubik_mcp_...). Required."
    },
    "table": {
      "type": "string",
      "enum": [
        "article_profiles",
        "consolidation_pack_observations"
      ],
      "description": "Which kind of change to undo, matching the undo_token's origin (create_article_profile -> article_profiles, log_pack_observation -> consolidation_pack_observations)."
    },
    "undo_token": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The undo_token returned by the original confirmed create_article_profile or log_pack_observation call."
    }
  },
  "required": [
    "api_key",
    "table",
    "undo_token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Reconciles a shipment's export documents against each other and returns the seven checks from the kubik.tools Export-Set: whether the gross weights add up, whether every net weight comes from a measured source or is marked as an estimate, whether the values match the invoice TOTAL (freight and loading as their own line, not a subtotal), whether each Kollo's allocated articles equal that Kollo's own gross — per package, never in aggregate, whether the net weights on the invoice tie to the Speditionsauftrag article for article, whether the mandatory fields (tariff number and country of origin) are filled on every position, and whether the same article carries the same tariff number across every document supplied, matched through the alias table rather than by string equality. Give it the sheets as plain rows of cells — exactly what you would read out of the spreadsheet, header row and title block included. Do NOT pre-clean them: where the header sits relative to a title block is one of the things the engine reads, and removing blank rows or columns destroys it. invoice and packing are required; spedi (the forwarder's Speditionsauftrag) is optional and, when present, is what checks 5 and 7 compare against instead of the packing list. What it does NOT do: it does not produce the Exportdatenblatt workbook, it does not invent a tariff number or a country of origin (a missing one is reported by check 6, never filled in), and it does not store anything — no row of these documents is kept or logged. Read the verdict first. It names what to do next, not a score: "pass" — every check ran and agreed; "attention" — at least one check found the documents contradicting each other, and flagged_checks names which; "confirm_aliases" — no contradiction, but an article number on one document has no counterpart on the other, which a human confirms as an alias rather than fixes; "incomplete" — a check could not run at all (no Kollo was found on the packing list), so this is not a pass and skipped_checks says which check was lost. A flagged check is the product working, not failing — the gate exists to surface a disagreement between documents before it reaches customs. Check titles and details come back in German, verbatim as they are printed on the Abstimmung sheet the human sees, so that what you report and what they read are the same words.

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Your team's kubik.tools MCP API key (kubik_mcp_...). Required."
    },
    "invoice": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "description": "The commercial invoice sheet. Required."
    },
    "packing": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "description": "The packing list sheet. Required."
    },
    "spedi": {
      "description": "The forwarder's Speditionsauftrag, if you have it. Optional — checks 5 and 7 compare against it when present.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "invoice_sheet_name": {
      "description": "Sheet name as it appears in the workbook. Cosmetic; defaults to 'Rechnung'.",
      "type": "string"
    },
    "packing_sheet_name": {
      "description": "Sheet name as it appears in the workbook. Cosmetic; defaults to 'Packliste'.",
      "type": "string"
    },
    "spedi_sheet_name": {
      "description": "Sheet name as it appears in the workbook. Cosmetic; defaults to 'Speditionsauftrag'.",
      "type": "string"
    }
  },
  "required": [
    "api_key",
    "invoice",
    "packing"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Calculates loading metres (Lademeter, LDM) -- the floor-space unit (Ladefläche) that governs European road freight -- for a list of cargo pieces, plus the equivalent number of pallet places (Palettenstellplätze, Stellplätze). Answers questions like "wie viele Lademeter" or "wieviel Platz brauche ich im Lkw". Units: length_cm and width_cm (Länge/Breite in cm) per piece. weight_kg_per_piece (Gewicht in kg) is optional. Formula: LDM = sum(length_cm x width_cm x quantity) / reference_deck_width_cm / 100. Height is irrelevant here -- LDM is a floor-footprint metric, not a volume one (for volumetric/chargeable weight, use calculate_chargeable_weight instead). Reference width: Lademeter (LDM) is always computed at the fixed 240cm (2.4m) reference lane -- this is a commercial road-freight convention, not a DIN/EN/ISO/VDI standard, and does not vary by vehicle. If vehicle_id names one of the loadable vehicle profiles (e.g. "semi_136" = Sattelzug 13,6 m, "rigid_75" = 7,5-Tonner), the response additionally reports deck_length_m: how much of that specific vehicle's own deck length the cargo occupies -- a different, vehicle-specific quantity, not the LDM figure. Pallet-place equivalents are also computed at the 240cm reference lane. Worked example: 8 Europaletten/EUR-Paletten (120cm x 80cm) at the standard 240cm width = (120*80*8)/240/100 = 3.2 LDM, equivalent to 8 Palettenstellplätze (one Europalette occupies 0.4 LDM at this width). An Industriepalette (120x100cm) occupies more floor space per unit: 0.5 LDM at the same width. Edge cases: an unknown vehicle_id returns the list of available vehicles instead of guessing -- it never silently picks one. If any piece omits weight_kg_per_piece, total_weight_kg is returned as null rather than an incomplete partial sum. Maximum 100 piece lines (use quantity to combine identical pieces).

{
  "type": "object",
  "properties": {
    "pieces": {
      "description": "List of cargo pieces (up to 100 line items, required, non-empty). Use quantity to combine identical pieces rather than repeating rows.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "quantity": {
            "description": "Number of identical pieces in this line. Must be a positive number.",
            "type": "number"
          },
          "length_cm": {
            "description": "Length of one piece, in centimeters (Länge in cm). Must be a positive number.",
            "type": "number"
          },
          "width_cm": {
            "description": "Width of one piece, in centimeters (Breite in cm). Must be a positive number.",
            "type": "number"
          },
          "weight_kg_per_piece": {
            "description": "Actual weight of one piece, in kilograms (Gewicht in kg). Optional -- omit if unknown.",
            "type": "number"
          }
        }
      }
    },
    "vehicle_id": {
      "description": "Optional vehicle profile id (e.g. \"semi_136\" = Sattelzug 13,6 m, \"rigid_75\" = 7,5-Tonner). Does not change the LDM calculation (always the fixed 240cm reference lane) -- adds deck_length_m, how much of that vehicle's own deck length the cargo occupies. If given but not recognized, the response lists every available vehicle instead of guessing.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Checks whether a list of cargo pieces fits a named vehicle. Two capacity limits always checked: loading metres (Lademeter, LDM, Stellplätze) and, if weight is given, payload (Zuladung, Nutzlast). When every piece ALSO carries height_cm, a third, stronger check runs too: a real 3D placement simulation (the SAME stacking/shelf-packing engine kubik.tools' own planner uses, not an approximation) -- this becomes the authoritative fits verdict, since it can correctly say "fits" for a load that stacks well even when the raw floor-footprint LDM math alone would have said "doesn't fit". Still not Ladungssicherung (load securing) or axle-load distribution. Vehicle profiles (vehicle_id -> German name): "semi_136" = Sattelzug/Sattelauflieger 13,6 m (colloquially also "40-Tonner"), "curtain_136" = Planensattel 13,6 m, "flatbed_136" = Pritsche 13,6 m, "rigid_75" = 7,5-Tonner, "midi_12" = 12-Tonner/Koffer-Lkw, "rigid_18" = 18-Tonner, "rigid_26" = 26-Tonner (3-Achser), "drawbar_40" = Hängerzug, "sprinter_l3h2" = Mercedes Sprinter L3H2 (3,5t), "ducato_l4h2" = Fiat Ducato L4H2 (3,5t), "cont_20"/"cont_40"/"cont_40hc" = 20-/40-/40-Fuß-HC-Container. Cargo like a Gitterbox/Rollbehälter is just another piece by footprint -- no separate cargo-type parameter needed. Units: length_cm/width_cm/height_cm per piece in centimetres (Länge/Breite/Höhe in cm), weight_kg_per_piece in kilograms (Gewicht in kg). height_cm is optional -- omit it and only the LDM/payload check runs; weight_kg_per_piece is optional too -- if omitted, the payload check is honestly skipped, not guessed. rotatable (default true) says whether a piece may be turned 90° on the floor to fit; fragile (default false) marks a piece nothing heavier should stack on top of, unless it's genuinely load-bearing. Three modes, by what's given: (1) vehicle_id + pieces -> full fit check; if it does NOT fit, the response additionally includes recommended_vehicles -- the smallest fitting alternatives by payload, e.g. cargo that overloads a 7,5-Tonner might fit a 12-Tonner or 18-Tonner instead (suggest, never auto-pick). (2) vehicle_id alone, no pieces -> that vehicle's own payload_kg/max_ldm_m/deck_width_cm, a plain spec lookup (e.g. "wie viele Stellplätze hat ein Standard-Sattelzug" or "maximale Zuladung Sattelzug"). (3) neither given, or pieces given with no vehicle_id -> the full vehicle list, filtered to fitting ones when pieces were given. An unrecognized vehicle_id also returns the full list -- it never assumes which vehicle you mean. Worked example: 6 Europaletten (120x80cm), 4.8 tonnes total, against vehicle_id "rigid_75" -- loading metres (2.5 LDM) are well within the 6.2m limit, but 4800kg exceeds the 3500kg payload, so fits=false, limiting_constraint="payload", recommended_vehicles lists "midi_12" (12-Tonner) and "rigid_18" (18-Tonner) first -- the smallest vehicles that hold 4.8t. Edge cases: if no vehicle profile fits the given cargo at all, says so honestly ("exceeds all vehicle profiles") rather than recommending an impossible option. Utilisation percentages are uncapped on purpose (an overloaded plan reads "137%", not a reassuring clamped "100%"). Maximum 100 piece lines.

{
  "type": "object",
  "properties": {
    "pieces": {
      "description": "List of cargo pieces (up to 100 line items), optionally omitted entirely to just look up a vehicle's specs (with vehicle_id) or list all vehicles (without). Use quantity to combine identical pieces rather than repeating rows.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "quantity": {
            "description": "Number of identical pieces in this line. Must be a positive number.",
            "type": "number"
          },
          "length_cm": {
            "description": "Length of one piece, in centimeters (Länge in cm). Must be a positive number.",
            "type": "number"
          },
          "width_cm": {
            "description": "Width of one piece, in centimeters (Breite in cm). Must be a positive number.",
            "type": "number"
          },
          "height_cm": {
            "description": "Height of one piece, in centimeters (Höhe in cm). Optional -- if every piece in the request has it, a real 3D placement simulation runs too, not just the LDM/floor-space formula.",
            "type": "number"
          },
          "weight_kg_per_piece": {
            "description": "Actual weight of one piece, in kilograms (Gewicht in kg). Optional -- omit if unknown; the payload/Zuladung check is skipped rather than guessed.",
            "type": "number"
          },
          "rotatable": {
            "description": "Whether this piece may be turned 90° on the floor to fit (only used by the placement simulation, i.e. only when height_cm is given). Defaults to true.",
            "type": "boolean"
          },
          "fragile": {
            "description": "Whether this piece is fragile -- nothing should stack on it unless the item below is genuinely load-bearing (only used by the placement simulation). Defaults to false.",
            "type": "boolean"
          }
        }
      }
    },
    "vehicle_id": {
      "description": "Vehicle profile id to check against or look up (e.g. \"semi_136\" = Sattelzug 13,6 m, \"rigid_75\" = 7,5-Tonner). If omitted or not recognized, the response lists every available vehicle instead of guessing.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}