Skip to main content
Glama

CutOptim Engine

Optimize timber

optimize_wood

Metered: one Engine API call. Cut timber parts grouped by cross-section from matching stock lengths. Timber optimization (cross-section-aware 1D). Cut lengths from bars that have a CROSS-SECTION. Unlike /v1/optimize/1d, where every bar can serve every part, a 50×150 part can only come out of 50×150 stock — so the job is split by cross-section, each section is matched to its own stock and solved separately, and the response carries both per-section and job-wide totals.

Fanning the same job out into several /v1/optimize/1d calls is not equivalent: it costs one call per section against your quota, moves the stock matching to your code, and cannot distinguish "no material of this section" from "did not fit" — which this endpoint reports separately as unmatched and unplaced.

sw and sh may be given in either order: 50×100 and 100×50 are the same bar turned over and are matched as one section. The response reports the normalised short/long form.

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": "optimize_wood"
  }
}

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 timber parts to cut, one row per part type: cross-section `sw` × `sh`, `length`, optional `qty`.
stockYesAt most 50 rows. Since every cross-section needs at least one stock row, this is also the practical ceiling on cross-sections in a single job; a wider catalogue should be split into several requests.
engineNoAs in 1D, `max` is not offered here (a **400** before a call is charged). `balanced` resolves to the same packer as `heuristic`: within a section a timber job is a length problem, and free nesting has nothing to offer it. The value is accepted, echoed back, and a warning states which packer actually ran.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.
optionsNoIdentical to `Options1D` — a cross-section changes what fits, not how a bar is cut.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields 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"
      +}
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "properties": {
      +      "contractVersion": {
      +        "type": "string"
      +      },
      +      "csv": {
      +        "type": "string"
      +      },
      +      "cutPlan": {
      +        "items": {
      +          "allOf": [
      +            {
      +              "properties": {
      +                "angle": {
      +                  "type": "number"
      +                },
      +                "axis": {
      +                  "enum": [
      +                    "h",
      +                    "v"
      +                  ],
      +                  "type": "string"
      +                },
      +                "bevel": {
      +                  "type": "number"
      +                },
      +                "length": {
      +                  "minimum": 0,
      +                  "type": "number"
      +                },
      +                "pos": {
      +                  "type": "number"
      +                },
      +                "sheet": {
      +                  "minimum": 0,
      +                  "type": "integer"
      +                },
      +                "stage": {
      +                  "minimum": 1,
      +                  "type": "integer"
      +                },
      +                "step": {
      +                  "minimum": 1,
      +                  "type": "integer"
      +                }
      +              },
      +              "required": [
      +                "sheet",
      +                "step",
      +                "axis",
      +                "pos",
      +                "length",
      +                "stage"
      +              ],
      +              "type": "object"
      +            }
      +          ],
      +          "properties": {
      +            "section": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "section"
      +          ],
      +          "type": "object"
      +        },
      +        "type": [
      +          "array",
      +          "null"
      +        ]
      +      },
      +      "deterministic": {
      +        "const": true,
      +        "type": "boolean"
      +      },
      +      "dxf": {
      +        "type": "string"
      +      },
      +      "engine": {
      +        "enum": [
      +          "heuristic",
      +          "balanced"
      +        ],
      +        "type": "string"
      +      },
      +      "engineVersion": {
      +        "type": "string"
      +      },
      +      "metrics": {
      +        "properties": {
      +          "cuts": {
      +            "type": "integer"
      +          },
      +          "placed": {
      +            "type": "integer"
      +          },
      +          "rodCount": {
      +            "type": "integer"
      +          },
      +          "sectionCount": {
      +            "type": "integer"
      +          },
      +          "sharedCuts": {
      +            "type": "integer"
      +          },
      +          "toleranceAcceptedCount": {
      +            "type": "integer"
      +          },
      +          "total": {
      +            "type": "integer"
      +          },
      +          "totalPrice": {
      +            "type": "number"
      +          },
      +          "yieldPct": {
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "sectionCount",
      +          "rodCount",
      +          "yieldPct",
      +          "placed",
      +          "total",
      +          "cuts",
      +          "totalPrice",
      +          "toleranceAcceptedCount"
      +        ],
      +        "type": "object"
      +      },
      +      "sections": {
      +        "items": {
      +          "properties": {
      +            "material": {
      +              "type": "string"
      +            },
      +            "metrics": {
      +              "properties": {
      +                "cuts": {
      +                  "type": "integer"
      +                },
      +                "placed": {
      +                  "type": "integer"
      +                },
      +                "rodCount": {
      +                  "type": "integer"
      +                },
      +                "total": {
      +                  "type": "integer"
      +                },
      +                "totalPrice": {
      +                  "type": "number"
      +                },
      +                "yieldPct": {
      +                  "type": "number"
      +                }
      +              },
      +              "required": [
      +                "rodCount",
      +                "yieldPct",
      +                "placed",
      +                "total",
      +                "cuts",
      +                "totalPrice"
      +              ],
      +              "type": "object"
      +            },
      +            "rods": {
      +              "items": {
      +                "properties": {
      +                  "length": {
      +                    "type": "number"
      +                  },
      +                  "material": {
      +                    "type": "string"
      +                  },
      +                  "meta": {
      +                    "type": "object"
      +                  },
      +                  "offcuts": {
      +                    "items": {
      +                      "type": "number"
      +                    },
      +                    "type": "array"
      +                  },
      +                  "parts": {
      +                    "items": {
      +                      "properties": {
      +                        "flipped": {
      +                          "enum": [
      +                            "face",
      +                            "edge",
      +                            "roll"
      +                          ],
      +                          "type": "string"
      +                        },
      +                        "length": {
      +                          "type": "number"
      +                        },
      +                        "meta": {
      +                          "type": "object"
      +                        },
      +                        "name": {
      +                          "type": "string"
      +                        },
      +                        "pos": {
      +                          "type": "number"
      +                        },
      +                        "sharedCut": {
      +                          "properties": {
      +                            "angle": {
      +                              "type": "number"
      +                            },
      +                            "bevel": {
      +                              "type": "number"
      +                            },
      +                            "kerfAlongAxis": {
      +                              "type": "number"
      +                            },
      +                            "lead": {
      +                              "type": "number"
      +                            }
      +                          },
      +                          "required": [
      +                            "angle",
      +                            "bevel",
      +                            "kerfAlongAxis",
      +                            "lead"
      +                          ],
      +                          "type": "object"
      +                        }
      +                      },
      +                      "required": [
      +                        "name",
      +                        "pos",
      +                        "length"
      +                      ],
      +                      "type": "object"
      +                    },
      +                    "type": "array"
      +                  },
      +                  "price": {
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "remaining": {
      +                    "type": "number"
      +                  }
      +                },
      +                "required": [
      +                  "length",
      +                  "price",
      +                  "remaining",
      +                  "parts"
      +                ],
      +                "type": "object"
      +              },
      +              "type": "array"
      +            },
      +            "section": {
      +              "type": "string"
      +            },
      +            "sh": {
      +              "type": "number"
      +            },
      +            "stockName": {
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "sw": {
      +              "type": "number"
      +            },
      +            "unplaced": {
      +              "items": {
      +                "properties": {
      +                  "length": {
      +                    "type": "number"
      +                  },
      +                  "name": {
      +                    "type": "string"
      +                  },
      +                  "qty": {
      +                    "minimum": 1,
      +                    "type": "integer"
      +                  }
      +                },
      +                "required": [
      +                  "name",
      +                  "length",
      +                  "qty"
      +                ],
      +                "type": "object"
      +              },
      +              "type": "array"
      +            }
      +          },
      +          "required": [
      +            "section",
      +            "sw",
      +            "sh",
      +            "stockName",
      +            "rods",
      +            "metrics",
      +            "unplaced"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "timing": {
      +        "properties": {
      +          "solveMs": {
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "solveMs"
      +        ],
      +        "type": "object"
      +      },
      +      "unmatched": {
      +        "items": {
      +          "properties": {
      +            "material": {
      +              "type": "string"
      +            },
      +            "parts": {
      +              "items": {
      +                "properties": {
      +                  "length": {
      +                    "type": "number"
      +                  },
      +                  "name": {
      +                    "type": "string"
      +                  },
      +                  "qty": {
      +                    "minimum": 1,
      +                    "type": "integer"
      +                  }
      +                },
      +                "required": [
      +                  "name",
      +                  "length",
      +                  "qty"
      +                ],
      +                "type": "object"
      +              },
      +              "type": "array"
      +            },
      +            "qty": {
      +              "type": "integer"
      +            },
      +            "section": {
      +              "type": "string"
      +            },
      +            "sh": {
      +              "type": "number"
      +            },
      +            "sw": {
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "section",
      +            "sw",
      +            "sh",
      +            "parts",
      +            "qty"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "unplaced": {
      +        "items": {
      +          "properties": {
      +            "length": {
      +              "type": "number"
      +            },
      +            "name": {
      +              "type": "string"
      +            },
      +            "qty": {
      +              "minimum": 1,
      +              "type": "integer"
      +            }
      +          },
      +          "required": [
      +            "name",
      +            "length",
      +            "qty"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "warnings": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "engine",
      +      "engineVersion",
      +      "contractVersion",
      +      "deterministic",
      +      "sections",
      +      "unmatched",
      +      "metrics",
      +      "unplaced",
      +      "warnings",
      +      "timing"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "engine": {
      +        "enum": [
      +          "heuristic",
      +          "balanced"
      +        ],
      +        "type": "string"
      +      },
      +      "jobId": {
      +        "format": "uuid",
      +        "type": "string"
      +      },
      +      "mode": {
      +        "enum": [
      +          "wood"
      +        ],
      +        "type": "string"
      +      },
      +      "pollAfterMs": {
      +        "type": "integer"
      +      },
      +      "quota": {
      +        "properties": {
      +          "limit": {
      +            "type": "integer"
      +          },
      +          "reserved": {
      +            "type": "integer"
      +          },
      +          "used": {
      +            "type": "integer"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "status": {
      +        "enum": [
      +          "running"
      +        ],
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "jobId",
      +      "status",
      +      "mode",
      +      "engine",
      +      "pollAfterMs"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedOutput schema / properties
      Removed value: -{
      -  "contractVersion": {
      -    "type": "string"
      -  },
      -  "csv": {
      -    "type": "string"
      -  },
      -  "cutPlan": {
      -    "items": {
      -      "allOf": [
      -        {
      -          "properties": {
      -            "angle": {
      -              "type": "number"
      -            },
      -            "axis": {
      -              "enum": [
      -                "h",
      -                "v"
      -              ],
      -              "type": "string"
      -            },
      -            "bevel": {
      -              "type": "number"
      -            },
      -            "length": {
      -              "minimum": 0,
      -              "type": "number"
      -            },
      -            "pos": {
      -              "type": "number"
      -            },
      -            "sheet": {
      -              "minimum": 0,
      -              "type": "integer"
      -            },
      -            "stage": {
      -              "minimum": 1,
      -              "type": "integer"
      -            },
      -            "step": {
      -              "minimum": 1,
      -              "type": "integer"
      -            }
      -          },
      -          "required": [
      -            "sheet",
      -            "step",
      -            "axis",
      -            "pos",
      -            "length",
      -            "stage"
      -          ],
      -          "type": "object"
      -        }
      -      ],
      -      "properties": {
      -        "section": {
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "section"
      -      ],
      -      "type": "object"
      -    },
      -    "type": [
      -      "array",
      -      "null"
      -    ]
      -  },
      -  "deterministic": {
      -    "const": true,
      -    "type": "boolean"
      -  },
      -  "dxf": {
      -    "type": "string"
      -  },
      -  "engine": {
      -    "enum": [
      -      "heuristic",
      -      "balanced"
      -    ],
      -    "type": "string"
      -  },
      -  "engineVersion": {
      -    "type": "string"
      -  },
      -  "metrics": {
      -    "properties": {
      -      "cuts": {
      -        "type": "integer"
      -      },
      -      "placed": {
      -        "type": "integer"
      -      },
      -      "rodCount": {
      -        "type": "integer"
      -      },
      -      "sectionCount": {
      -        "type": "integer"
      -      },
      -      "sharedCuts": {
      -        "type": "integer"
      -      },
      -      "toleranceAcceptedCount": {
      -        "type": "integer"
      -      },
      -      "total": {
      -        "type": "integer"
      -      },
      -      "totalPrice": {
      -        "type": "number"
      -      },
      -      "yieldPct": {
      -        "type": "number"
      -      }
      -    },
      -    "required": [
      -      "sectionCount",
      -      "rodCount",
      -      "yieldPct",
      -      "placed",
      -      "total",
      -      "cuts",
      -      "totalPrice",
      -      "toleranceAcceptedCount"
      -    ],
      -    "type": "object"
      -  },
      -  "sections": {
      -    "items": {
      -      "properties": {
      -        "material": {
      -          "type": "string"
      -        },
      -        "metrics": {
      -          "properties": {
      -            "cuts": {
      -              "type": "integer"
      -            },
      -            "placed": {
      -              "type": "integer"
      -            },
      -            "rodCount": {
      -              "type": "integer"
      -            },
      -            "total": {
      -              "type": "integer"
      -            },
      -            "totalPrice": {
      -              "type": "number"
      -            },
      -            "yieldPct": {
      -              "type": "number"
      -            }
      -          },
      -          "required": [
      -            "rodCount",
      -            "yieldPct",
      -            "placed",
      -            "total",
      -            "cuts",
      -            "totalPrice"
      -          ],
      -          "type": "object"
      -        },
      -        "rods": {
      -          "items": {
      -            "properties": {
      -              "length": {
      -                "type": "number"
      -              },
      -              "material": {
      -                "type": "string"
      -              },
      -              "meta": {
      -                "type": "object"
      -              },
      -              "offcuts": {
      -                "items": {
      -                  "type": "number"
      -                },
      -                "type": "array"
      -              },
      -              "parts": {
      -                "items": {
      -                  "properties": {
      -                    "flipped": {
      -                      "enum": [
      -                        "face",
      -                        "edge",
      -                        "roll"
      -                      ],
      -                      "type": "string"
      -                    },
      -                    "length": {
      -                      "type": "number"
      -                    },
      -                    "meta": {
      -                      "type": "object"
      -                    },
      -                    "name": {
      -                      "type": "string"
      -                    },
      -                    "pos": {
      -                      "type": "number"
      -                    },
      -                    "sharedCut": {
      -                      "properties": {
      -                        "angle": {
      -                          "type": "number"
      -                        },
      -                        "bevel": {
      -                          "type": "number"
      -                        },
      -                        "kerfAlongAxis": {
      -                          "type": "number"
      -                        },
      -                        "lead": {
      -                          "type": "number"
      -                        }
      -                      },
      -                      "required": [
      -                        "angle",
      -                        "bevel",
      -                        "kerfAlongAxis",
      -                        "lead"
      -                      ],
      -                      "type": "object"
      -                    }
      -                  },
      -                  "required": [
      -                    "name",
      -                    "pos",
      -                    "length"
      -                  ],
      -                  "type": "object"
      -                },
      -                "type": "array"
      -              },
      -              "price": {
      -                "type": [
      -                  "number",
      -                  "null"
      -                ]
      -              },
      -              "remaining": {
      -                "type": "number"
      -              }
      -            },
      -            "required": [
      -              "length",
      -              "price",
      -              "remaining",
      -              "parts"
      -            ],
      -            "type": "object"
      -          },
      -          "type": "array"
      -        },
      -        "section": {
      -          "type": "string"
      -        },
      -        "sh": {
      -          "type": "number"
      -        },
      -        "stockName": {
      -          "type": [
      -            "string",
      -            "null"
      -          ]
      -        },
      -        "sw": {
      -          "type": "number"
      -        },
      -        "unplaced": {
      -          "items": {
      -            "properties": {
      -              "length": {
      -                "type": "number"
      -              },
      -              "name": {
      -                "type": "string"
      -              },
      -              "qty": {
      -                "minimum": 1,
      -                "type": "integer"
      -              }
      -            },
      -            "required": [
      -              "name",
      -              "length",
      -              "qty"
      -            ],
      -            "type": "object"
      -          },
      -          "type": "array"
      -        }
      -      },
      -      "required": [
      -        "section",
      -        "sw",
      -        "sh",
      -        "stockName",
      -        "rods",
      -        "metrics",
      -        "unplaced"
      -      ],
      -      "type": "object"
      -    },
      -    "type": "array"
      -  },
      -  "timing": {
      -    "properties": {
      -      "solveMs": {
      -        "type": "number"
      -      }
      -    },
      -    "required": [
      -      "solveMs"
      -    ],
      -    "type": "object"
      -  },
      -  "unmatched": {
      -    "items": {
      -      "properties": {
      -        "material": {
      -          "type": "string"
      -        },
      -        "parts": {
      -          "items": {
      -            "properties": {
      -              "length": {
      -                "type": "number"
      -              },
      -              "name": {
      -                "type": "string"
      -              },
      -              "qty": {
      -                "minimum": 1,
      -                "type": "integer"
      -              }
      -            },
      -            "required": [
      -              "name",
      -              "length",
      -              "qty"
      -            ],
      -            "type": "object"
      -          },
      -          "type": "array"
      -        },
      -        "qty": {
      -          "type": "integer"
      -        },
      -        "section": {
      -          "type": "string"
      -        },
      -        "sh": {
      -          "type": "number"
      -        },
      -        "sw": {
      -          "type": "number"
      -        }
      -      },
      -      "required": [
      -        "section",
      -        "sw",
      -        "sh",
      -        "parts",
      -        "qty"
      -      ],
      -      "type": "object"
      -    },
      -    "type": "array"
      -  },
      -  "unplaced": {
      -    "items": {
      -      "properties": {
      -        "length": {
      -          "type": "number"
      -        },
      -        "name": {
      -          "type": "string"
      -        },
      -        "qty": {
      -          "minimum": 1,
      -          "type": "integer"
      -        }
      -      },
      -      "required": [
      -        "name",
      -        "length",
      -        "qty"
      -      ],
      -      "type": "object"
      -    },
      -    "type": "array"
      -  },
      -  "warnings": {
      -    "items": {
      -      "type": "string"
      -    },
      -    "type": "array"
      -  }
      -}
    • removedOutput schema / required
      Removed value: -[
      -  "engine",
      -  "engineVersion",
      -  "contractVersion",
      -  "deterministic",
      -  "sections",
      -  "unmatched",
      -  "metrics",
      -  "unplaced",
      -  "warnings",
      -  "timing"
      -]
  2. Changed1 schema field changed
    • addedInput schema / properties / parts / description
      Added value: +"The timber parts to cut, one row per part type: cross-section `sw` × `sh`, `length`, optional `qty`."
  3. Changed7 schema fields changed
    • addedInput schema / properties / options / properties / mitrePairing
      Added value: +{
      +  "default": false,
      +  "description": "Pair parts of one section whose facing ends (`parts[].ends`) can share ONE saw cut. Off by default: a request without it is solved exactly as before. On, a plan with pairs is returned only when it ranks strictly better than the unpaired plan by the packer's own ranking (parts placed first, then material — or price with `minimizeCost`); otherwise the unpaired plan comes back. Pairs only, no chains of three or more.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / parts / items / properties / ends
      Added value: +{
      +  "description": "Angled ends (mitre pairing). The `angle` is seen on `sh` AS ENTERED and the `bevel` on `sw`, so send the section the way the angles were measured.",
      +  "properties": {
      +    "end": {
      +      "description": "One end cut of a part, in degrees from square (0 = a square end), signed. The part is measured long point to long point (`length` is its overall length). A part whose two end cuts would cross inside its section (shorter than its leads) cannot be made: a 400 `invalid_request` naming `parts[i].ends` says how long it must at least be.",
      +      "properties": {
      +        "angle": {
      +          "description": "The face angle: the mitre or plumb cut as seen on the `depth` side (wood: on `sh` as entered).",
      +          "exclusiveMaximum": 90,
      +          "exclusiveMinimum": -90,
      +          "type": "number"
      +        },
      +        "bevel": {
      +          "default": 0,
      +          "description": "The edge angle: the bevel as seen on the `thickness` side (wood: on `sw` as entered). A compound cut has both.",
      +          "exclusiveMaximum": 90,
      +          "exclusiveMinimum": -90,
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "angle"
      +      ],
      +      "type": "object"
      +    },
      +    "start": {
      +      "description": "One end cut of a part, in degrees from square (0 = a square end), signed. The part is measured long point to long point (`length` is its overall length). A part whose two end cuts would cross inside its section (shorter than its leads) cannot be made: a 400 `invalid_request` naming `parts[i].ends` says how long it must at least be.",
      +      "properties": {
      +        "angle": {
      +          "description": "The face angle: the mitre or plumb cut as seen on the `depth` side (wood: on `sh` as entered).",
      +          "exclusiveMaximum": 90,
      +          "exclusiveMinimum": -90,
      +          "type": "number"
      +        },
      +        "bevel": {
      +          "default": 0,
      +          "description": "The edge angle: the bevel as seen on the `thickness` side (wood: on `sw` as entered). A compound cut has both.",
      +          "exclusiveMaximum": 90,
      +          "exclusiveMinimum": -90,
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "angle"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / parts / items / properties / flip
      Added value: +{
      +  "default": "none",
      +  "description": "Mitre pairing only: which 180° turns of the part on the bar are allowed, so its angled end can meet a neighbour's. `none` (default — a profiled moulding or one-sided stock), `face` (end for end, the crown or top edge stays up — roof members), `edge` (end for end over the edge — flat stock, frames), `any`.",
      +  "enum": [
      +    "none",
      +    "face",
      +    "edge",
      +    "any"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / properties / cutPlan / items / allOf
      Previous value: -[
      -  {
      -    "properties": {
      -      "axis": {
      -        "enum": [
      -          "h",
      -          "v"
      -        ],
      -        "type": "string"
      -      },
      -      "length": {
      -        "minimum": 0,
      -        "type": "number"
      -      },
      -      "pos": {
      -        "type": "number"
      -      },
      -      "sheet": {
      -        "minimum": 0,
      -        "type": "integer"
      -      },
      -      "stage": {
      -        "minimum": 1,
      -        "type": "integer"
      -      },
      -      "step": {
      -        "minimum": 1,
      -        "type": "integer"
      -      }
      -    },
      -    "required": [
      -      "sheet",
      -      "step",
      -      "axis",
      -      "pos",
      -      "length",
      -      "stage"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "properties": {
      +      "angle": {
      +        "type": "number"
      +      },
      +      "axis": {
      +        "enum": [
      +          "h",
      +          "v"
      +        ],
      +        "type": "string"
      +      },
      +      "bevel": {
      +        "type": "number"
      +      },
      +      "length": {
      +        "minimum": 0,
      +        "type": "number"
      +      },
      +      "pos": {
      +        "type": "number"
      +      },
      +      "sheet": {
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "stage": {
      +        "minimum": 1,
      +        "type": "integer"
      +      },
      +      "step": {
      +        "minimum": 1,
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "sheet",
      +      "step",
      +      "axis",
      +      "pos",
      +      "length",
      +      "stage"
      +    ],
      +    "type": "object"
      +  }
      +]
    • addedOutput schema / properties / metrics / properties / sharedCuts
      Added value: +{
      +  "type": "integer"
      +}
    • addedOutput schema / properties / sections / items / properties / rods / items / properties / parts / items / properties / flipped
      Added value: +{
      +  "enum": [
      +    "face",
      +    "edge",
      +    "roll"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / sections / items / properties / rods / items / properties / parts / items / properties / sharedCut
      Added value: +{
      +  "properties": {
      +    "angle": {
      +      "type": "number"
      +    },
      +    "bevel": {
      +      "type": "number"
      +    },
      +    "kerfAlongAxis": {
      +      "type": "number"
      +    },
      +    "lead": {
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "angle",
      +    "bevel",
      +    "kerfAlongAxis",
      +    "lead"
      +  ],
      +  "type": "object"
      +}
  4. First observed

TDQS

A4.8/5.0
Behavior5/5

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

The description adds substantial behavior beyond the annotations: metered billing once per written plan, async `auto` behavior with 202/jobId, 504 `solve_timeout` without `async`, no charge on failed solve, and separate reporting of `unmatched` versus `unplaced`. These are operationally important traits not carried by the annotations.

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 description is front-loaded with the purpose and metered-call note, then proceeds through the key distinctions and error behavior. It is somewhat long, but the sentences are purposeful and the structure supports scanning.

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 complex optimization endpoint with nested parameters, this description covers the core model, billing, async behavior, error handling, and response distinction between per-section and job-wide results. Since an output schema exists, it does not need to explain return fields in detail.

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 schema does most parameter documentation. The description still adds useful semantic meaning: `sw`/`sh` are order-independent, cross-section grouping determines stock matching, and unmatched versus unplaced failures mean different things.

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 description states a specific verb and resource: cutting timber parts grouped by cross-section from matching stock lengths. It explicitly distinguishes the operation from `/v1/optimize/1d` and explains why cross-section-aware matching is a different job.

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

Usage Guidelines5/5

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

It clearly frames when this endpoint is needed versus `/v1/optimize/1d`, explaining that parts can only come from stock of the same cross-section. It also explicitly says fanning the same job into several 1D calls is not equivalent and lists the practical consequences.

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.