FreightUtils MCP Server

pallet_fitting_calculator

Read-onlyIdempotent

Calculate how many identical boxes fit on a pallet by layer, height, rotation, and weight limits, with totals, footprint, and volume utilisation.

Instructions

Calculate how many identical boxes fit on a pallet: boxes per layer (trying 90-degree rotation when allowed), layer count within the max height, totals, footprint and volume utilisation, and weight capping.

Behavior: deterministic geometric packing of one box size in aligned rows and columns — it does not model interlocked or mixed-orientation patterns; weight_limited reports when max_payload_kg caps the count below the geometric fit, counted in whole layers (notes say when a part layer is left out, and why nothing fits when no box fits); pallet_deck_height_cm defaults to 15. Missing or non-positive dimensions error naming the parameter. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: boxes_per_layer, layers, total_boxes, orientation, boxes_per_row/col, usable_height_cm, utilisation_percent (the share of the pallet FOOTPRINT one layer covers), volume_utilisation_percent (box volume over the usable envelope), total_box_volume_cbm, wasted_space_cbm, max_boxes_by_weight, notes and the weight fields under result, plus confidence, _source and citation (the FreightUtils v1 response envelope). Field names as this package serves them (snake_case); the hosted /api/mcp endpoint serves the same fields in camelCase (e.g. total_cbm → totalCbm).

Limitations: a theoretical best-effort fit — real stacking obeys carton strength, overhang and load-stability rules it does not model.

Related: ldm_calculator (pallets into trailer length), vehicle_lookup (pallet capacity per vehicle), container_lookup (pallets into containers).

Input Schema

TableJSON Schema

Name	Required	Description
`box_width_cm`	Yes	Box width in cm.
`box_height_cm`	Yes	Box height in cm.
`box_length_cm`	Yes	Box length in cm.
`box_weight_kg`	No	Weight per box in kg — enables the weight-capping check.
`allow_rotation`	No	Try 90-degree box rotation for the best layer fit. Default: true.
`max_payload_kg`	No	Maximum pallet payload in kg. Example: 1000.
`pallet_width_cm`	Yes	Pallet width in cm. Example: 80 (euro pallet).
`pallet_length_cm`	Yes	Pallet length in cm. Example: 120 (euro pallet).
`pallet_max_height_cm`	Yes	Maximum stack height in cm INCLUDING the pallet deck. Example: 180.
`pallet_deck_height_cm`	No	Pallet deck height in cm. Default: 15.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`ok`	Yes
`result`	Yes
`_source`	Yes
`citation`	Yes
`validity`	No
`warnings`	No
`confidence`	Yes
`blocking_errors`	No
`envelope_version`	Yes
`normalized_input`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv2.17.2Aug 21, 2026
- addedOutput schema / properties / _source / properties / authority_current_edition
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / _source / properties / checked_at
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / _source / properties / dataset_edition
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / envelope_version / const
```
Removed value: -"1"
```
- addedOutput schema / properties / envelope_version / enum
```
Added value: +[
+  "1",
+  "1.1"
+]
```

Changed11 schema fields changedv2.11.0Jul 10, 2026

changedInput schema / properties / allow_rotation / description

Previous value: -"Allow 90-degree box rotation (default: true)"New value: +"Try 90-degree box rotation for the best layer fit. Default: true."

changedInput schema / properties / box_height_cm / description

Previous value: -"Box height in cm"New value: +"Box height in cm."

changedInput schema / properties / box_length_cm / description

Previous value: -"Box length in cm"New value: +"Box length in cm."

changedInput schema / properties / box_weight_kg / description

Previous value: -"Box weight in kg"New value: +"Weight per box in kg — enables the weight-capping check."

changedInput schema / properties / box_width_cm / description

Previous value: -"Box width in cm"New value: +"Box width in cm."

changedInput schema / properties / max_payload_kg / description

Previous value: -"Maximum pallet payload weight in kg"New value: +"Maximum pallet payload in kg. Example: 1000."

changedInput schema / properties / pallet_deck_height_cm / description

Previous value: -"Pallet deck height in cm (default: 15)"New value: +"Pallet deck height in cm. Default: 15."

changedInput schema / properties / pallet_length_cm / description

Previous value: -"Pallet length in cm"New value: +"Pallet length in cm. Example: 120 (euro pallet)."

changedInput schema / properties / pallet_max_height_cm / description

Previous value: -"Maximum stack height in cm (including pallet deck)"New value: +"Maximum stack height in cm INCLUDING the pallet deck. Example: 180."

changedInput schema / properties / pallet_width_cm / description

Previous value: -"Pallet width in cm"New value: +"Pallet width in cm. Example: 80 (euro pallet)."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "_source": {
+      "additionalProperties": false,
+      "properties": {
+        "checked": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "provenance_status": {
+          "enum": [
+            "verified",
+            "pending-verification",
+            "computed",
+            "live"
+          ],
+          "type": "string"
+        },
+        "source_url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "checked",
+        "provenance_status"
+      ],
+      "type": "object"
+    },
+    "blocking_errors": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "recovery": {
+            "additionalProperties": false,
+            "properties": {
+              "action": {
+                "type": "string"
+              },
+              "params": {
+                "additionalProperties": {},
+                "type": "object"
+              },
+              "tool": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "action"
+            ],
+            "type": "object"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "recovery"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "citation": {
+      "additionalProperties": false,
+      "properties": {
+        "qualifier": {
+          "type": "string"
+        },
+        "text": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "text"
+      ],
+      "type": "object"
+    },
+    "confidence": {
+      "additionalProperties": false,
+      "properties": {
+        "basis": {
+          "enum": [
+            "deterministic",
+            "provenance",
+            "match_quality",
+            "freshness"
+          ],
+          "type": "string"
+        },
+        "level": {
+          "enum": [
+            "high",
+            "medium",
+            "low"
+          ],
+          "type": "string"
+        },
+        "score": {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        }
+      },
+      "required": [
+        "level",
+        "basis"
+      ],
+      "type": "object"
+    },
+    "envelope_version": {
+      "const": "1",
+      "type": "string"
+    },
+    "normalized_input": {
+      "additionalProperties": {},
+      "type": "object"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "result": {
+      "anyOf": [
+        {
+          "additionalProperties": true,
+          "properties": {
+            "boxes_per_col": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "boxes_per_layer": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "boxes_per_row": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "layers": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "meta": {
+              "anyOf": [
+                {
+                  "additionalProperties": {},
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "orientation": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "pallet_volume_cbm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "remaining_weight_capacity_kg": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "total_box_volume_cbm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "total_boxes": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "total_weight_kg": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "usable_height_cm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "utilisation_percent": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "wasted_space_cbm": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "weight_limited": {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            }
+          },
+          "type": "object"
+        },
+        {
+          "additionalProperties": {},
+          "type": "object"
+        }
+      ]
+    },
+    "validity": {
+      "additionalProperties": false,
+      "properties": {
+        "as_of": {
+          "type": "string"
+        },
+        "effective_from": {
+          "type": "string"
+        },
+        "effective_to": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "as_of"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "details": {
+            "additionalProperties": {},
+            "type": "object"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "envelope_version",
+    "ok",
+    "result",
+    "confidence",
+    "_source",
+    "citation"
+  ],
+  "type": "object"
+}

First observedv1.0.0Apr 3, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish the safe read-only, idempotent profile, and the description adds substantial context beyond that: deterministic aligned-row packing with no interlocked/mixed-orientation modelling, weight_limited semantics for payload capping in whole layers, the pallet_deck_height_cm default of 15, error behaviour naming the offending parameter, and rate-limit errors carrying reset_at. This is exactly the value-add structured fields cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is long, but it is clearly front-loaded and partitioned into Behavior / Returns / Limitations / Related labels, and nearly every sentence carries distinct operational information. A minor amount of the Returns enumeration could be trimmed since an output schema exists, but nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter computational tool with an output schema, the description covers behaviour, defaults, error and rate-limit handling, output field semantics, a camelCase/snake_case caveat, and explicit modelling limitations. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that allow_rotation triggers a 90-degree attempt, that weight_limited reports payload capping below geometric fit, and how whole-layer counting and the part-layer note work. It also clarifies the output naming convention (snake_case here vs camelCase on the hosted endpoint).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ('Calculate how many identical boxes fit on a pallet') and enumerates the exact outputs (boxes per layer, layer count, totals, utilisation, weight capping). The Related line explicitly distinguishes it from ldm_calculator, vehicle_lookup and container_lookup, so an agent can tell it apart from siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The Related section names three sibling tools and gives each one's distinct scope (pallets into trailer length, pallet capacity per vehicle, pallets into containers), which is strong routing context. It stops short of explicit when-to-use/when-not-to-use phrasing, so it is clear context rather than full conditional guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.