Skip to main content
Glama

Get Cost Breakdown

get_cost_breakdown
Read-onlyIdempotent

Get the itemised cost sheet of a calculation as one tree: headline, cost category, operation and feature, with time and cost side by side. Use it when someone needs the line items, for a negotiation, a work plan or a design review. Each line carries its time, its rate and the factor keys that move it, which preview_cost accepts. persona selects the tiers and quantity restates the headline, times and cost tier at another lot size. max_depth sets how deep the cost sheet goes (default 2, the categories and one tier beneath; null for the whole tree), and a line cut short says in children_hidden how many lines it hides. Also returns the stock the part is bought as, with its scrap and remnant credits. For a short summary, use explain_cost. Read-only and free.

Input Schema

NameRequiredDescriptionDefault
personaNoWhich tiers to return: 'full' (the default, every tier), 'procurement' (headline and band), 'workprep' (the operations as a work plan), 'operations' (operations and machines) or 'design' (the cost sheet and feature drivers).full
quantityNoLot size to read the headline, the times and the cost tier at; omit for the lot the calculation was priced for. The operations, feature and material_stock tiers describe the priced lot either way.
max_depthNoHow many tiers of cost_lines to return: 1 the cost categories only, 2 (the default) the categories and the tier beneath, null the whole tree. A line cut short states in children_hidden how many lines sit beneath it. With a depth set, a line also leaves out the keys it has no value for (null, [] or {}).
calculation_idYesId of a calculation, as upload_and_quote, quote_part or list_calculations return it.

Output Schema

NameRequiredDescriptionDefault
basisNoWhere the figures at `quantity` come from: 'priced' (the ordered lot, exact), 'curve_point' (recorded on the calculation's lot-size curve while pricing) or 'restated' (priced from the same closed form the curve was built from). Null when the calculation records no lot-size curve.
errorNoWhy this calculation produced no price, in one sentence, when its status is terminal (failed / cancelled).
statusYes
personaYesThe persona view this result is sliced for.
currencyNoThe calculation's currency; every money figure here is in it.
featuresNo
guidanceYes
machinesNo
quantityNoThe lot size this result is stated at: the calculation's own ordered lot unless `quantity` was passed, in which case the headline, the times and the cost tier are all at that lot size.
cost_bandNo[low, high] prediction band for the unit cost. Stated at the lot the calculation was priced at only: the band is fitted to that run and does not carry to another quantity.
unit_costNoUnit cost per part at `quantity`: direct cost plus overhead_var and overhead_fixed. Where the costing environment states no Material-/Fertigungsgemeinkosten, overhead_var is the flat variable overhead the environment states (none by default); once it states them, those overheads sit above unit_cost as cost-sheet rungs, with administration and selling, margin and the other surcharges. The price to quote is offer_price.
confidenceNoQuote-trust signal — the headline the procurement / supplier persona reads together with the prediction band.
cost_linesNoThe itemised cost sheet as a tree — every category with the tiers beneath it, each carrying its time, its rate and the factors that move it.
operationsNo
setup_costNoSetup cost for the whole lot at `quantity`, in `currency` — the sheet's setup line times the lot.
total_costNounit_cost for the whole lot at `quantity`, on the same basis as unit_cost.
offer_priceNoThe offer price per unit — unit_cost plus the cost-sheet surcharges the costing environment states; equal to unit_cost when no sheet is stated. The SAME figure explain_cost states, so the shareable procurement headline is the price, not the bare manufacturing cost. Absent on older calculations.
unit_time_sNoTime per unit at `quantity`, in seconds, across every activity: machine time plus the bench work plus the per-part programming and inspection shares. One meaning at every lot size, and never smaller than `machine_time_s`. Null at a lot size a calculation priced before the two were told apart.
needs_reviewNoTrue when this cost needs a human check before it is trusted. Reported for EVERY persona — a trust flag must never be sliced away, or a persona that doesn't get the review tier reads a flagged cost as clean.
setup_time_sNoSetup time for the whole lot at `quantity`, in seconds.
material_noteNo
calculation_idYes
machine_time_sNoMachine time per unit at `quantity`, in seconds: the billable run plus the finishing pass under the allowance.
material_stockNoThe stock the part is bought as — format, size, parts per stock — its mass balance, and the material line's purchase and credits, at the lot the calculation was priced for whichever quantity was asked. Null on a catalogue part and on a calculation priced before 2026-08-28, which recorded no material detail; one priced before the 2026-09-26 release states no scrap or remnant mass and no bar length.
cost_categoriesNoPer-unit cost by category, keyed by the cost sheet's own bucket slugs (material, setup, machine, labour, programming, tooling, inspection, finishing, subcontract, then the surcharge ladder). The top level of ``cost_lines`` flattened: same numbers, in the calculation's currency, adding up to the price per part.
currency_factorNoWhat every money figure here was multiplied by to carry it from the environment's rate currency into `currency`; 1.0 when the two are the same. The prices and per-lot charges in a cost line's `label_params` are in the rate currency, so a line's amount is that arithmetic (mass x price per kilogram, time x rate) times this factor — and times the calibration it was charged at on a calibrated environment. Absent where the calculation does not state it.
machine_name_at_nNoThe machine the figures at `quantity` were priced on, where it differs from or restates the calculation's own route.
material_resolvedNo
selection_failureNoThe same refusal as data when no machine in the costing environment could make the part.
cost_sheet_rebuiltNoTrue when the sheet was reconstructed from the rates, times and cost lines this calculation stored rather than recorded while it was priced. A reconstructed sheet carries the cost categories and the surcharge ladder but not the per-machine, per-clamping or per-operation tiers — those are recorded only while pricing and cannot be derived afterwards. Every amount is the amount charged either way. Null when no sheet was read for this persona.
costing_environment_idNoThe costing environment this was priced in: the machines, rates and overheads the factors named in each line's ``factors`` belong to.
inputs_changed_since_runNoNull when this price reflects every input on its part revision. Otherwise {roles, corrections, latest_at}: files attached and corrections applied to the part after the run read its inputs, which a new calculation reads and this one did not.
environment_changed_since_runNoNull when this price was computed on its costing environment as it stands. Otherwise {latest_at}: the environment was edited after the run read it, and a new calculation prices with the current setup while this result does not.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedOutput schema / $defs / CostSheetNode / properties / amount / description
      Previous value: -"What this line costs per unit, in the calculation's currency."New value: +"What this line costs per unit, in the calculation's currency, as shown: a tier adds up exactly to the line above it."
    • addedOutput schema / $defs / CostSheetNode / properties / exact
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "This line's amount before it was rounded for display; a per-lot figure is it times the lot, rounded once."
      +}
    • changedOutput schema / properties / material_stock / description
      Previous value: -"The stock the part is bought as — format, size, parts per stock — its mass balance, and the material line's purchase and credits, at the lot the calculation was priced for whichever quantity was asked. Null on a bought-in part and on a calculation priced before 2026-08-28, which recorded no material detail; one priced before the 2026-09-26 release states no scrap or remnant mass and no bar length."New value: +"The stock the part is bought as — format, size, parts per stock — its mass balance, and the material line's purchase and credits, at the lot the calculation was priced for whichever quantity was asked. Null on a catalogue part and on a calculation priced before 2026-08-28, which recorded no material detail; one priced before the 2026-09-26 release states no scrap or remnant mass and no bar length."
  2. Changed7 schema fields changed
    • addedInput schema / properties / calculation_id / format
      Added value: +"uuid"
    • changedInput schema / properties / max_depth / description
      Previous value: -"How many tiers of cost_lines to return: 1 the cost categories only, 2 (the default) the categories and the tier beneath, null the whole tree. A line cut short states in children_hidden how many lines sit beneath it."New value: +"How many tiers of cost_lines to return: 1 the cost categories only, 2 (the default) the categories and the tier beneath, null the whole tree. A line cut short states in children_hidden how many lines sit beneath it. With a depth set, a line also leaves out the keys it has no value for (null, [] or {})."
    • addedOutput schema / $defs / CostDriverLine / properties / category
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Set on a cost-category row: its key in cost_categories (setup, subcontract, material, machine …), or 'other' on the row that holds every category not listed. Absent on a feature or component row."
      +}
    • changedOutput schema / $defs / CostDriverLine / properties / cost / description
      Previous value: -"Cost contribution per unit, in the calculation's currency (the result's `currency`) — the DIRECT run-time cost the feature consumes (machine, labour and finishing time), before any setup, programming, tooling or overhead is spread onto it. The tenant's cost-driver card can show the same rows fully loaded, so its per-feature figure is higher than this by one uniform factor; the ranking and the relative shares are identical on both bases."New value: +"Cost contribution per unit, in the calculation's currency (the result's `currency`). On a cost-category row it is that line of the cost sheet. On a feature row it is the DIRECT run-time cost the feature consumes (machine, labour and finishing time), before any setup, programming, tooling or overhead is spread onto it. The tenant's cost-driver card can show the feature rows fully loaded, so its per-feature figure is higher than this by one uniform factor; the ranking and the relative shares are identical on both bases."
    • changedOutput schema / $defs / CostDriverLine / properties / cost_share_pct / description
      Previous value: -"Share of unit cost, 0–100, on the same direct basis as cost. Sum the listed rows against attributed_cost_share_pct, not against 100."New value: +"Share of unit cost, 0–100, on the same basis as cost. The category rows, 'other' included, add up to 100. The feature rows add up to the share the named features explain (attributed_cost_share_pct where the result states it), not to 100."
    • changedOutput schema / $defs / CostDriverLine / properties / rank / description
      Previous value: -"1 = the largest driver."New value: +"1 = the largest driver. Cost categories and features are ranked separately; null on the row that holds the categories not listed."
    • changedOutput schema / properties / unit_cost / description
      Previous value: -"Unit cost per part at `quantity`: direct cost plus overhead_var and overhead_fixed. Where the costing environment states no Material-/Fertigungsgemeinkosten, overhead_var is the flat variable overhead (platform default 15 % of direct cost); once it states them, that default is 0 and those overheads sit above unit_cost as cost-sheet rungs, with administration and selling, margin and the other surcharges. The price to quote is offer_price."New value: +"Unit cost per part at `quantity`: direct cost plus overhead_var and overhead_fixed. Where the costing environment states no Material-/Fertigungsgemeinkosten, overhead_var is the flat variable overhead the environment states (none by default); once it states them, those overheads sit above unit_cost as cost-sheet rungs, with administration and selling, margin and the other surcharges. The price to quote is offer_price."
  3. Changed2 schema fields changed
    • addedInput schema / properties / max_depth
      Added value: +{
      +  "anyOf": [
      +    {
      +      "minimum": 1,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": 2,
      +  "description": "How many tiers of cost_lines to return: 1 the cost categories only, 2 (the default) the categories and the tier beneath, null the whole tree. A line cut short states in children_hidden how many lines sit beneath it."
      +}
    • addedOutput schema / $defs / CostSheetNode / properties / children_hidden
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "How many lines sit beneath this one that `max_depth` left out: ask again with a larger `max_depth`, or null, to see them. Absent when nothing beneath this line was left out."
      +}
  4. Changed6 schema fields changed
    • addedInput schema / properties / calculation_id / description
      Added value: +"Id of a calculation, as upload_and_quote, quote_part or list_calculations return it."
    • addedInput schema / properties / persona / description
      Added value: +"Which tiers to return: 'full' (the default, every tier), 'procurement' (headline and band), 'workprep' (the operations as a work plan), 'operations' (operations and machines) or 'design' (the cost sheet and feature drivers)."
    • changedOutput schema / $defs / CostSheetNode / properties / factors / description
      Previous value: -"Adjustable factors that move this line, by name — the keys get_cost_factors publishes and preview_cost accepts. A factor is listed only where this line carries what is needed to work it out, so an empty list does not mean the line is fixed."New value: +"Adjustable factors that move this line, by name: the keys preview_cost accepts. A factor is listed only where this line carries what is needed to work it out, so an empty list does not mean the line is fixed."
    • changedOutput schema / $defs / ProcessStepLine / properties / subcontract_per_part / description
      Previous value: -"What this step is charged per part at the ordered lot size, in the calculation's currency — set only on an outsourced post-machining step (heat treatment, coating), and part of the subcontract cost line. Null on a machining step: machining cost attributes to features, not to operations (use get_cost_drivers). Null too when the charge was not recorded."New value: +"What this step is charged per part at the ordered lot size, in the calculation's currency — set only on an outsourced post-machining step (heat treatment, coating), and part of the subcontract cost line. Null on a machining step: machining cost attributes to features, not to operations (explain_cost ranks them). Null too when the charge was not recorded."
    • changedOutput schema / description
      Previous value: -"One calculation as a single rough-to-detailed hierarchy — headline →\ncost category → operation → feature, with time and cost side by side — so\nevery persona can stop at the depth it needs from the SAME run.\n\n``persona`` selects the slice: 'procurement' (headline + band only),\n'workprep' (the routing / operations tier), 'operations' (routing + machines\nfor balancing), 'design' (cost categories + per-feature drivers), or 'full'\n(every tier). Tiers not relevant to the persona come back empty.\n\nThe category tier is the itemised cost sheet: ``cost_lines`` is the whole\ntree — cost category, then per machine, per clamping, per work element —\nand ``cost_categories`` is its top level flattened for a quick read. Both\ncome from the one sheet the cost-sheet endpoint serves and the app renders,\nso an agent and a person read the same numbers rather than two\nderivations of them. This is the CATEGORY axis of the cost; for the\nFEATURE axis (which pocket, which hole) use get_cost_drivers."New value: +"One calculation as a single rough-to-detailed hierarchy — headline →\ncost category → operation → feature, with time and cost side by side — so\nevery persona can stop at the depth it needs from the SAME run.\n\n``persona`` selects the slice: 'procurement' (headline + band only),\n'workprep' (the routing / operations tier), 'operations' (routing + machines\nfor balancing), 'design' (cost categories + per-feature drivers), or 'full'\n(every tier). Tiers not relevant to the persona come back empty.\n\nThe category tier is the itemised cost sheet: ``cost_lines`` is the whole\ntree — cost category, then per machine, per clamping, per work element —\nand ``cost_categories`` is its top level flattened for a quick read. Both\ncome from the one sheet the cost-sheet endpoint serves and the app renders,\nso an agent and a person read the same numbers rather than two\nderivations of them. This is the CATEGORY axis of the cost; for the\nFEATURE axis (which pocket, which hole) explain_cost ranks the drivers."
    • changedOutput schema / properties / costing_environment_id / description
      Previous value: -"The costing environment this was priced in. get_cost_factors takes it and reads the factors named in each line's ``factors``, their range and where each one is saved."New value: +"The costing environment this was priced in: the machines, rates and overheads the factors named in each line's ``factors`` belong to."
  5. Changed1 schema field changed
    • changedOutput schema / properties / costing_environment_id / description
      Previous value: -"The costing environment this was priced in — pass it to get_cost_factors to read the factors named in each line's ``factors``, their range and where each one is saved."New value: +"The costing environment this was priced in. get_cost_factors takes it and reads the factors named in each line's ``factors``, their range and where each one is saved."
  6. Changed2 schema fields changed
    • changedOutput schema / $defs / ConfidenceSignal / description
      Previous value: -"Quote-trust headline — is this number calibrated to the shop, or a model\nestimate? The signal a procurement / supplier persona reads alongside the\nprediction band before trusting a should-cost."New value: +"Quote-trust headline — is this number calibrated to the shop, or a model\nestimate? The signal a procurement / supplier persona reads alongside the\nprediction band."
    • changedOutput schema / properties / confidence / description
      Previous value: -"Quote-trust signal — the headline the procurement / supplier persona reads with the band before trusting the should-cost."New value: +"Quote-trust signal — the headline the procurement / supplier persona reads together with the prediction band."
  7. Added

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, so the bar is lower, yet the description still adds real behavior: the call is 'free', max_depth defaults to 2, cut lines report children_hidden, keys with no value are omitted when a depth is set, and quantity only restates headline/times/cost tier. It stops short of describing ordering or size limits, so not a 5.

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 purpose and tree shape are front-loaded, then usage cases, then per-parameter behavior — a logical order with little filler. It is dense and long for a read tool, and the material_stock sentence sits mid-paragraph rather than with the other return-shape content, which costs it a point.

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?

With an output schema present, return values need no explanation, yet the description still flags the notable extras (truncation via children_hidden, null-key omission, material stock with scrap/remnant credits). Given four params and full schema coverage, an agent has everything needed to call it correctly.

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 baseline is 3; the description still adds interpretive value by explaining that persona 'selects the tiers', that quantity only moves the headline/times/cost tier while other tiers stay at the priced lot, and that the returned factor keys are what preview_cost accepts. These are cross-tool semantics the schema text does not fully convey.

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 ('Get the itemised cost sheet of a calculation') and describes the exact shape returned — a tree of headline, cost category, operation and feature with time and cost side by side. It explicitly separates itself from explain_cost (short summary) and links to preview_cost for the factor keys, so an agent can tell it apart from siblings.

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?

Gives concrete use cases ('when someone needs the line items, for a negotiation, a work plan or a design review') and names the alternative for the lighter case: 'For a short summary, use explain_cost.' Nothing about tool selection is left to inference.

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.