Skip to main content
Glama

CutOptim Engine

Validate a 2D request

validate_2d
Read-onlyIdempotent

Free, no key needed: checks a 2D request without solving it. Same arguments as optimize_2d (field descriptions there). Validate a 2D request — free, no key, no quota, no solve. Schema-validate the SAME body /v1/optimize/2d takes, WITHOUT solving or spending a call. 200 {valid:true, warnings} (warnings flag parts that fit no stock — an approximate, solve-free probe), or 400 with the exact bad field path. Open like /v1/health: validate payloads during integration before you even have a key. The engine verdict matches the optimize path exactly, engine: "max" included: a body this endpoint accepts is one /v1/optimize/2d will accept, and one it refuses (400 for an option the max tier cannot model, 503 where that tier is not enabled) is refused there too.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "parts": "<parts>",
      "stock": "<stock>"
    },
    "name": "validate_2d"
  }
}

Input Schema

NameRequiredDescriptionDefault
asyncNoOpt in to answers that may arrive later. With `"auto"` a job that finishes within the synchronous time limit still answers 200 with the plan, exactly as without it; a job that would outgrow the limit answers **202** with a `jobId` instead, keeps solving, and its plan is read with `GET /v1/jobs/{id}` (the same poll as engine `max`). The call is billed once, when the plan is written; a solve that fails is not billed. Without this field such a job answers 504 `solve_timeout` with the `jobId` in `details` and is not charged. The official SDKs send it and wait for the job for you.
partsYesThe rectangular parts to cut, one row per part type (`w`, `h`, optional `qty`, `name`, grain, edge banding).
stockYesThe sheet sizes to cut from, one row per size (`w`, `h`, optional `qty`, `price`).
engineNoWhich optimizer to run. `heuristic` is the guillotine multi-strategy packer: highest yield, every layout edge-to-edge saw-cuttable, always a full `cutPlan`. `balanced` is a MaxRects free-nesting packer: much faster on large jobs for a small yield cost, but its layouts are often not guillotine (`guillotineValid: false`, `cutPlan: null`), and it does not model `tolerance`, `minimizeCost`, `grainGroup`, `maxCutStages` or `minimizeRotations` — set one of those and a string in `warnings` tells you it was ignored. `max` is the ASYNCHRONOUS tree-search tier (2D only): it reaches the proven optimum on far more jobs at the cost of seconds-to-a-minute per solve, so instead of a plan it returns **202** with a `jobId` — poll `GET /v1/jobs/{id}` for the result. Still deterministic and guillotine-valid. Where the tier is not enabled on a deployment, `engine: "max"` fails closed with **503**. **What `max` models.** It packs ONE stock format at full sheet size with unlimited supply and a fixed 3-stage guillotine pattern. Anything that would make the returned plan physically WRONG is therefore REFUSED with **400** at submission — before a call is reserved and before you wait for the solve: a second `stock` row, `options.trim`, `options.respectStock`, any `material`, any `grainGroup`, a non-empty `matchedSets` (an empty one is fine). Options that only make the plan less tuned are accepted and listed in `warnings`: `tolerance`, `minimizeCost`, `maxCutStages` (fixed at 3), `minimizeRotations`, `firstCut`, `effort`. A `max` result reports no `offcuts`. Send those jobs to `heuristic`. The default never changes silently.heuristic
includeNoThree kinds of token. NARROWING (`cutPlan`, `offcuts`): omit the field entirely to get both; a present array keeps only the narrowing tokens it lists (an empty array drops both). ADDITIVE EXPORT (`svg`, `csv`, `dxf`): each adds an inline export STRING to the response (`svg` a standalone 2D layout — 2D only, a warning is returned for 1D/wood; `dxf` an R12/AC1009 drawing; `csv` a cut list, RFC 4180 quoted (a part name with a comma or a quote stays one field) and formula-injection-guarded (a name beginning with `=`, `+`, `-`, `@`, TAB or CR is prefixed with an apostrophe so a spreadsheet reads it as text, not a formula — CWE-1236). 2D DATA (`labels`, `planHash`, `pdf`, `labelsPdf`): `labels` adds per-piece label data (`labels[]`, see `Label2D`), `planHash` a 64-hex fingerprint of the plan (the same plan always gives the same hash), `pdf` the cutting-plan PDF and `labelsPdf` the label PDF, both base64-encoded and drawn by the same code as the CutOptim app. These four are 2D only: a 1D or wood request returns a `warnings` entry instead. `pdf` renders at most 500 parts (total quantity); a larger 2D request with `pdf` is a 413 `too_large` with `details.path: "include"`. Export and data tokens do not affect narrowing, so `["svg"]` adds svg and — listing no narrowing token — drops cutPlan/offcuts; use `["cutPlan","offcuts","svg"]` to keep everything.
optionsNoKerf, trim, first-cut direction, cost and stock rules, effort and label output; every field is optional.
matchedSetsNoMatched sets (grain matching): groups of parts cut side by side from one piece of board. Send a NON-EMPTY ARRAY of sets (at most 50); members are named by `parts[].id`. Only a non-empty array switches the feature on: absent, `null`, `[]` — and any value that is not an array — is a request without sets, answered exactly as before (no error). With sets the response adds `sheets[].parts[].matchedSet` on every member and a `matchedSets` rollup; `csv` gains `Set` and `Position` columns at the end, `svg` the `matched-sets` frame group, `dxf` the position code on LABELS; `pdf` and `labelsPdf` draw the members as ordinary parts for now (a `warnings` line says so; the set marks are in `sheets[].parts[].matchedSet`, `csv` and `svg`). Engine `max` refuses a non-empty array (400 `details.unsupported`); an empty one is fine. 2D only: the 1D, wood and nest endpoints ignore this field and `parts[].id`.

Output Schema

NameRequiredDescriptionDefault
modeYes
partsYes
stockYes
validYes
warningsYes
engineEnabledNo
contractVersionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / async
      Added value: +{
      +  "description": "Opt in to answers that may arrive later. With `\"auto\"` a job that finishes within the synchronous time limit still answers 200 with the plan, exactly as without it; a job that would outgrow the limit answers **202** with a `jobId` instead, keeps solving, and its plan is read with `GET /v1/jobs/{id}` (the same poll as engine `max`). The call is billed once, when the plan is written; a solve that fails is not billed. Without this field such a job answers 504 `solve_timeout` with the `jobId` in `details` and is not charged. The official SDKs send it and wait for the job for you.",
      +  "enum": [
      +    "auto"
      +  ],
      +  "type": "string"
      +}
  2. Changed6 schema fields changed
    • addedInput schema / properties / engine / description
      Added value: +"Which optimizer to run. `heuristic` is the guillotine multi-strategy packer: highest yield, every layout edge-to-edge saw-cuttable, always a full `cutPlan`. `balanced` is a MaxRects free-nesting packer: much faster on large jobs for a small yield cost, but its layouts are often not guillotine (`guillotineValid: false`, `cutPlan: null`), and it does not model `tolerance`, `minimizeCost`, `grainGroup`, `maxCutStages` or `minimizeRotations` — set one of those and a string in `warnings` tells you it was ignored. `max` is the ASYNCHRONOUS tree-search tier (2D only): it reaches the proven optimum on far more jobs at the cost of seconds-to-a-minute per solve, so instead of a plan it returns **202** with a `jobId` — poll `GET /v1/jobs/{id}` for the result. Still deterministic and guillotine-valid. Where the tier is not enabled on a deployment, `engine: \"max\"` fails closed with **503**. **What `max` models.** It packs ONE stock format at full sheet size with unlimited supply and a fixed 3-stage guillotine pattern. Anything that would make the returned plan physically WRONG is therefore REFUSED with **400** at submission — before a call is reserved and before you wait for the solve: a second `stock` row, `options.trim`, `options.respectStock`, any `material`, any `grainGroup`, a non-empty `matchedSets` (an empty one is fine). Options that only make the plan less tuned are accepted and listed in `warnings`: `tolerance`, `minimizeCost`, `maxCutStages` (fixed at 3), `minimizeRotations`, `firstCut`, `effort`. A `max` result reports no `offcuts`. Send those jobs to `heuristic`. The default never changes silently."
    • addedInput schema / properties / include / description
      Added value: +"Three kinds of token. NARROWING (`cutPlan`, `offcuts`): omit the field entirely to get both; a present array keeps only the narrowing tokens it lists (an empty array drops both). ADDITIVE EXPORT (`svg`, `csv`, `dxf`): each adds an inline export STRING to the response (`svg` a standalone 2D layout — 2D only, a warning is returned for 1D/wood; `dxf` an R12/AC1009 drawing; `csv` a cut list, RFC 4180 quoted (a part name with a comma or a quote stays one field) and formula-injection-guarded (a name beginning with `=`, `+`, `-`, `@`, TAB or CR is prefixed with an apostrophe so a spreadsheet reads it as text, not a formula — CWE-1236). 2D DATA (`labels`, `planHash`, `pdf`, `labelsPdf`): `labels` adds per-piece label data (`labels[]`, see `Label2D`), `planHash` a 64-hex fingerprint of the plan (the same plan always gives the same hash), `pdf` the cutting-plan PDF and `labelsPdf` the label PDF, both base64-encoded and drawn by the same code as the CutOptim app. These four are 2D only: a 1D or wood request returns a `warnings` entry instead. `pdf` renders at most 500 parts (total quantity); a larger 2D request with `pdf` is a 413 `too_large` with `details.path: \"include\"`. Export and data tokens do not affect narrowing, so `[\"svg\"]` adds svg and — listing no narrowing token — drops cutPlan/offcuts; use `[\"cutPlan\",\"offcuts\",\"svg\"]` to keep everything."
    • addedInput schema / properties / matchedSets / description
      Added value: +"Matched sets (grain matching): groups of parts cut side by side from one piece of board. Send a NON-EMPTY ARRAY of sets (at most 50); members are named by `parts[].id`. Only a non-empty array switches the feature on: absent, `null`, `[]` — and any value that is not an array — is a request without sets, answered exactly as before (no error). With sets the response adds `sheets[].parts[].matchedSet` on every member and a `matchedSets` rollup; `csv` gains `Set` and `Position` columns at the end, `svg` the `matched-sets` frame group, `dxf` the position code on LABELS; `pdf` and `labelsPdf` draw the members as ordinary parts for now (a `warnings` line says so; the set marks are in `sheets[].parts[].matchedSet`, `csv` and `svg`). Engine `max` refuses a non-empty array (400 `details.unsupported`); an empty one is fine. 2D only: the 1D, wood and nest endpoints ignore this field and `parts[].id`."
    • addedInput schema / properties / options / description
      Added value: +"Kerf, trim, first-cut direction, cost and stock rules, effort and label output; every field is optional."
    • addedInput schema / properties / parts / description
      Added value: +"The rectangular parts to cut, one row per part type (`w`, `h`, optional `qty`, `name`, grain, edge banding)."
    • addedInput schema / properties / stock / description
      Added value: +"The sheet sizes to cut from, one row per size (`w`, `h`, optional `qty`, `price`)."
  3. Changed2 schema fields changed
    • addedInput schema / properties / parts / items / properties / qr
      Added value: +{
      +  "maxLength": 300,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / parts / items / properties / qrs
      Added value: +{
      +  "items": {
      +    "maxLength": 300,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 2000,
      +  "minItems": 1,
      +  "type": "array"
      +}
  4. Changed1 schema field changed
    • addedInput schema / properties / options / properties / labels
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "dimSize": {
      +      "default": "normal",
      +      "enum": [
      +        "normal",
      +        "large",
      +        "xl"
      +      ],
      +      "type": "string"
      +    },
      +    "factoryEdges": {
      +      "default": false,
      +      "type": "boolean"
      +    },
      +    "format": {
      +      "default": "sheet",
      +      "enum": [
      +        "sheet",
      +        "roll",
      +        "apli-03056",
      +        "brother-dk-11201"
      +      ],
      +      "type": "string"
      +    },
      +    "height": {
      +      "default": 40,
      +      "maximum": 300,
      +      "minimum": 15,
      +      "type": "number"
      +    },
      +    "hiddenFaceHint": {
      +      "default": false,
      +      "type": "boolean"
      +    },
      +    "offset": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "x": {
      +          "default": 0,
      +          "maximum": 20,
      +          "minimum": -20,
      +          "type": "number"
      +        },
      +        "y": {
      +          "default": 0,
      +          "maximum": 20,
      +          "minimum": -20,
      +          "type": "number"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "order": {
      +      "default": "input",
      +      "enum": [
      +        "input",
      +        "cut"
      +      ],
      +      "type": "string"
      +    },
      +    "partNo": {
      +      "default": false,
      +      "type": "boolean"
      +    },
      +    "parts": {
      +      "items": {
      +        "maximum": 999999,
      +        "minimum": 1,
      +        "type": "integer"
      +      },
      +      "maxItems": 500,
      +      "type": "array"
      +    },
      +    "stageWords": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "c2s": {
      +          "maxLength": 6,
      +          "type": "string"
      +        },
      +        "d": {
      +          "maxLength": 6,
      +          "type": "string"
      +        },
      +        "eb": {
      +          "maxLength": 6,
      +          "type": "string"
      +        },
      +        "rc": {
      +          "maxLength": 6,
      +          "type": "string"
      +        },
      +        "s": {
      +          "maxLength": 6,
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "stages": {
      +      "items": {
      +        "maxLength": 6,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "maxItems": 6,
      +      "type": "array"
      +    },
      +    "width": {
      +      "default": 100,
      +      "maximum": 300,
      +      "minimum": 20,
      +      "type": "number"
      +    }
      +  },
      +  "type": "object"
      +}
  5. First observed

TDQS

A4.4/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 cost (free, no key, no quota), the 200 shape `{valid:true, warnings}`, the 400 with an exact bad field path, and the 503 when the max tier is not enabled. It also states that the verdict is identical to the optimize path, including the `engine: "max"` 400/503 refusal parity, which is exactly the kind of contract an agent cannot infer from annotations.

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

Conciseness3/5

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

Front-loads the key facts well, but the 'free, no key, no quota, no solve' idea is restated three times in the opening sentences, which is pure redundancy. 'Open like `/v1/health`' is also oblique and costs a sentence without adding precision.

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

Completeness4/5

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

An output schema exists, so return values need less explanation, yet the description still documents the 200/400/503 outcomes and the warnings semantics (approximate, solve-free probe). Given 7 parameters and a large nested body, this is sufficient for an agent to call it correctly; only the 'see optimize_2d for field descriptions' shortcut leaves a small dependency.

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 already 100%, so the baseline is 3, but the description adds real semantic content: it explains that arguments mirror optimize_2d and, critically, that bodies refused by `max` (second stock row, trim, respectStock, material, grainGroup, non-empty matchedSets) are refused here too. The delegation 'field descriptions there' is a mild gap since it forces a cross-tool lookup.

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?

States a specific verb and resource: 'checks a 2D request without solving it' and 'Schema-validate the SAME body /v1/optimize/2d takes, WITHOUT solving or spending a call.' This cleanly separates it from the sibling optimize_2d, which does the actual solve.

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?

Gives a concrete when-to-use scenario ('validate payloads during integration before you even have a key') and points at optimize_2d for the real solve via 'same arguments as optimize_2d'. It never explicitly states the negative case ('do not use this to obtain a cut plan'), but the repeated 'no solve / no quota' framing makes the boundary clear.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.