Skip to main content
Glama

Family Materialize

family_materialize
Destructive

Builds every variant in a family from one design table, creating each part by recipe and assigning item and sequential part numbers. Supports instance and configuration modes.

Instructions

Materialize a whole variant family from ONE design table (issue #138, B1) — "make all the gears" becomes a table, not a loop. For each row, in table order, builds the part with its recipe (A1, #136) and allocates one item + one sequential part number (C1, #140). Subsumes standard-part catalogs: a bearing catalog is a family table keyed by designation, sourced from the ISO corpus.

Two modes (both supported): "instances" (each variant its own released file + part number) and "configurations" (variants share one artifact). Builds into the active document. Returns {schema, family, recipe, mode, key, count, rows, registry}.

table: path to the family table (.csv or .json). registry: optional items.json path (created if absent, written back). mode: optional override of the table's mode (instances|configurations).

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": {
      "table": "<table>"
    },
    "name": "family_materialize"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNo
tableYes
registryNo
workspaceNoRun this call in this named workspace

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds real context beyond them: it builds into the active document, allocates one item plus a sequential part number per row, and creates/writes back the registry file if absent. Those are meaningful side effects. It does not discuss reversibility or what happens on partial failure midway through the table, which is the remaining gap for a destructive tool.

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 core action and the modes, and the trailing parameter block is scannable. The internal issue/backlog references (#138, B1, #136, C1, #140) and the catalog-subsumption aside add noise an agent cannot act on, but the description is otherwise dense and well-ordered.

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 destructive, four-parameter tool with no output schema, the description covers the build target (active document), both execution modes, the registry side effect, and an explicit return shape {schema, family, recipe, mode, key, count, rows, registry}. An agent has enough to invoke it correctly and anticipate its effects.

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 only 25%, so the description has to carry the load, and it mostly does: it explains table accepts .csv or .json, registry is an optional items.json path that is created if absent and written back, and mode accepts 'instances' or 'configurations' — filling in the enum-less anyOf string that the schema leaves open. It doesn't describe the expected columns/keys of the family table itself.

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 — materialize a whole variant family from one design table — and immediately distinguishes itself from a per-part loop ('make all the gears becomes a table, not a loop'). It also carves out a domain ('subsumes standard-part catalogs'), so an agent can tell it apart from family_validate, recipe, and the individual add_* builders without opening the schema.

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

Usage Guidelines4/5

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

Gives clear usage context: one table-driven call instead of iterating, with both modes described and a note that it builds into the active document. It stops short of explicitly naming sibling alternatives (e.g., when to use family_validate first or items_resolve instead), so an agent must infer that boundary rather than being routed to it.

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

Deploy Server

Other Tools