Skip to main content
Glama
chartergroup

topopt

by chartergroup
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Compare runs

compare_runs
Read-onlyIdempotent

Compare two topology optimization runs or a base run with its variants, showing setup differences, metric deltas, and input inconsistencies side by side.

Instructions

Runs side by side: two runs (setup diff and metrics diff), or a base with its variants (one table). Reads files, writes nothing.

Give one form. (run_a, run_b): A is the base and B the change; delta is B - A. Every value names its source: run.json (what each run recorded at its start: the YAML path and the region file names, no hash), labels.bin, the YAML and STL files on disk (read now), and result/metrics.json. So the files on disk can be newer than the run or can differ from it; inputs says so as facts (a newer YAML or STL, YAML values that differ from run.json, labels from the files on disk that differ from labels.bin). The facts are evidence, not proof. (run_a, variants): run_a is the base; variants is a list of run folders, any number. One row per run, the base first.

run_a: the base run folder (relative paths start at the work folder). run_b: the changed run folder (two-run form). variants: the run folders of the table (table form); not together with run_b. check_labels: voxelize the YAML on disk and compare it with labels.bin (a few seconds on a big grid). null: do it when the grid has at most 10 million voxels. true: any grid size. false: skip it. Two-run keys: a, b, setup (run_json_diff, yaml_diff, region_files with the STL hashes, labels_diff: the voxel classes that changed, with the box in mm), metrics (rows with a, b, delta, delta_pct; stiffness per case; filter facts), inputs, notes (for example: the load cases differ, so compliance is not comparable), summary and problems. Table keys: base; runs (state, mass_final_g, mass_saved_pct, stiffness per load case from the optimizer, verdict, verify: done, not run or no result, print: a few print facts, render: the path of the newest montage PNG on disk, or null); vs_base (the setup diff of each variant against the base); notes; summary; problems. A fact that no file holds is null and an entry in problems. The table makes no image: render_part does. On a wrong call or folder: {"ok": false, "error": ...}.

Input Schema

NameRequiredDescriptionDefault
run_aYes
run_bNo
variantsNo
check_labelsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.5.0

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the read-only annotations, it discloses important behavior: it reads files and writes nothing, files on disk can be newer than or differ from a run, the reported facts are evidence rather than proof, and check_labels can cost seconds on a large grid with null meaning a 10-million-voxel threshold. It also describes the return shape and error behavior, which matters because there is no output schema.

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 two forms and the core read-only behavior, and most of its detail is useful for a complex comparison tool. It is dense and long, with some output-key detail that could be tightened, but it is not padded with empty boilerplate.

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 no output schema, four parameters, and complex comparison logic, the description supplies the missing context: both call forms, parameter behavior, data-provenance caveats, output keys for each form, null handling, problems reporting, and error behavior. An agent has enough information to choose a form and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: run_a is the base, run_b is the changed run in two-run form, variants is a list of run folders in table form, and check_labels has explicit null/true/false semantics. It also clarifies that relative paths start at the work folder and that run_b and variants are mutually exclusive.

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: compare two runs side by side, in either a two-run diff form or a base-plus-variants table form. It also distinguishes the tool from render_part by noting that the table makes no image, so an agent can tell what this tool does and does not do.

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?

It clearly explains the two call forms and warns that run_b and variants should not be used together, which is strong usage guidance. It also points to render_part for images, but it does not explicitly compare itself with several nearby siblings such as run_result, run_history, or list_runs.

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