FreightUtils MCP Server

pallet_fitting_calculator

Read-onlyIdempotent

Calculate how many identical boxes fit on a pallet, including boxes per layer, layer count, total boxes, orientation, weight capping, and footprint/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

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

Name	Required	Description	Default
`ok`	Yes
`_meta`	No
`as_of`	No
`result`	Yes
`status`	No
`_source`	Yes
`edition`	No
`citation`	Yes
`validity`	No
`warnings`	No
`confidence`	Yes
`missing_inputs`	No
`blocking_errors`	No
`envelope_version`	Yes
`normalized_input`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv2.27.0Oct 31, 2026

addedOutput schema / properties / _meta / properties / check_id
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / _meta / properties / edition_basis
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / _meta / properties / receipt

Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "created_at": {
+      "type": "string"
+    },
+    "dataset_version": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "engine_version": {
+      "type": "string"
+    },
+    "inputs": {},
+    "reason": {
+      "const": "key_required",
+      "type": "string"
+    },
+    "receipt_hash": {
+      "type": "string"
+    },
+    "result": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "schema_version": {
+      "type": "string"
+    },
+    "stored": {
+      "const": false,
+      "type": "boolean"
+    },
+    "tool": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "stored",
+    "reason",
+    "schema_version",
+    "receipt_hash",
+    "created_at",
+    "tool",
+    "inputs",
+    "dataset_version",
+    "engine_version",
+    "result"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / _meta / properties / receipt_url
```
Added value: +{
+  "type": "string"
+}
```

Changed10 schema fields changedv2.24.0Oct 29, 2026

addedOutput schema / properties / _meta

Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "identify": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

addedOutput schema / properties / as_of
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / blocking_errors / items / properties / recovery / properties / params / propertyNames
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / edition

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "applies_from": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "may_apply_until": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "applies_from",
+        "may_apply_until"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / properties / envelope_version / enum

Previous value: -[
-  "1",
-  "1.1"
-]New value: +[
+  "1",
+  "1.1",
+  "1.2"
+]

addedOutput schema / properties / missing_inputs

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / normalized_input / propertyNames
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / properties / result / anyOf

Previous value: -[
-  {
-    "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"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "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": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "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": {},
+    "propertyNames": {
+      "type": "string"
+    },
+    "type": "object"
+  }
+]

addedOutput schema / properties / status

Added value: +{
+  "enum": [
+    "ok",
+    "partial",
+    "not_found",
+    "unsupported",
+    "ambiguous"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / warnings / items / properties / details / propertyNames
```
Added value: +{
+  "type": "string"
+}
```

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?

Goes well past the readOnly/idempotent annotations: it discloses that packing is deterministic and geometry-only (no interlocked or mixed orientations), that weight capping is counted in whole layers with notes explaining partial-layer exclusion and zero-fit cases, that pallet_deck_height_cm defaults to 15, that missing or non-positive dimensions error with the offending parameter named, and that rate-limit errors carry a reset_at UTC timestamp. That is exactly the operational context annotations 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?

Front-loaded with the purpose, then cleanly sectioned into Behavior, Returns, Limitations and Related, so an agent can stop reading early. The Returns block is long and largely duplicates the existing output schema; the only non-redundant part is the snake_case vs camelCase field-naming caveat.

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 calculator with an output schema, this covers everything an agent needs to call it correctly: units, defaults, error conditions, rate-limit shape, determinism caveats and cross-tool routing. Nothing material is left to inference.

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 semantics: allow_rotation is framed as trying 90-degree rotation for best layer fit, deck height feeds usable_height_cm, and box_weight_kg/max_payload_kg interact to produce weight_limited and max_boxes_by_weight — the whole-layer rounding rule is stated only here, not in the schema.

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?

Opens with a specific verb and resource: 'Calculate how many identical boxes fit on a pallet', then enumerates the exact outputs (boxes per layer, layer count, totals, footprint/volume utilisation, weight capping). The closing Related list separates it from ldm_calculator, vehicle_lookup and container_lookup by naming each sibling's distinct domain.

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 routes the agent to alternatives with a parenthetical scoping of each, and the Limitations paragraph makes clear this is a theoretical single-box-size fit, implicitly excluding mixed-SKU or interlocked-pattern questions. What's missing is an explicit 'use X instead when Y' conditional statement, but the routing intent is unambiguous.

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