Skip to main content
Glama

Study Submit

study_submit

Sweep design variables over grid or Latin hypercube samples, evaluate each point's responses, and return a table that preserves every run for comparison and resumable re-execution.

Instructions

Sweep parameters over a sampled design space and record the WHOLE search as a table — the DOE primitive between the parametric layer and the solver catalog.

Without it, exploring a design space means hand-rolling recipe(params) -> solve -> mutate -> repeat and keeping only the last point, so nobody can tell afterwards whether the design is good or merely the one you stopped on. A study keeps every point, with the parameters that produced it.

variables declares the space; each entry is either explicit levels or a range:

  • {"name": "diameter_mm", "values": [8, 10, 12]} — these and only these

  • {"name": "diameter_mm", "min": 8, "max": 12, "levels": 3} — evenly spaced

sampling picks how they combine:

  • {"method": "grid"} (default) — full factorial. Exhaustive, and the only thing that can prove a trend, but it is the PRODUCT of the level counts: three variables at five levels is 125 evaluations.

  • {"method": "lhs", "n_samples": 20, "seed": 0} — Latin hypercube. Each variable's range is cut into n_samples strata and every stratum used once, so cost is decoupled from dimensionality: 20 points cover 6 variables as well as 2. Use it past 2-3 variables. Both are deterministic from seed, which is what makes a re-run hit the cache.

responses says how to measure each point, in the same mapping a performance requirement uses: {"name": "dp", "tool": "cfd_pipe_flow", "metric": "pressure_drop_pa", "conditions": {"diameter_mm": "$diameter_mm", "length_mm": 200}}. Inside conditions, "$<variable>" is that point's value and "$handle" is the part it built; an unknown $token is refused up front, because a sweep that silently measured a literal string at every point returns a flat, plausible, wrong table.

tool can be ANY AnkusDrive tool, including verify_performance — and that is the interesting case. A response that is a contract verdict carries a band, a trust block and a pass/fail/indeterminate state, so points stay comparable across fidelity tiers instead of being bare floats of unknown quality.

recipe (+ fixed_inputs) rebuilds geometry per point; omit it and pass handle (or nothing) to sweep analysis parameters against fixed geometry. Screening-tier responses evaluate inline in milliseconds, so thousand-point studies are viable; solver-tier responses fan out concurrently and one collector job joins them.

Caching IS resumability: identical points hash to the same job content key, so re-submitting a study after a crash, or widening its grid, re-runs only what is new — n_cached is what tells you the re-run was free. max_points (default 64) refuses a sweep larger than you probably meant.

objective — {"response": "dp", "sense": "min"} — additionally reports best.

Returns EITHER the finished table or {job_id, status, points, pending}; poll job_result for the completed table. A point that failed to build or measure is a row with ok: false, never an exception. Result: {ok, n_points, n_evaluated, n_cached, n_failed, sampling, variables, points: [{index, params, handle?, ok, responses: {name: {ok, value, band_pct?, converged?, state?, job_id?, cache_hit?, detail?}}, warnings}], responses: {name: {n, n_missing, min, max, mean, argmin, argmax}}, best?}.

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": {
      "variables": "<variables>",
      "responses": "<responses>"
    },
    "name": "study_submit"
  }
}

Input Schema

NameRequiredDescriptionDefault
handleNo
recipeNo
samplingNo
objectiveNo
responsesYes
variablesYes
workspaceNoRun this call in this named workspace
max_pointsNo
fixed_inputsNo

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.9/5.0
Behavior5/5

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

Annotations only declare writable-but-non-destructive and closed-world; the description adds the real behavioral context: caching equals resumability via a content hash, `max_points` (default 64) refuses oversized sweeps, unknown `$token` values are refused up front, failed points are returned as `ok: false` rows rather than exceptions, and re-runs/widened grids only run new points.

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 purpose, then segmented by parameter with bullets and inline examples, so it is scannable despite length. A few rhetorical sentences ('nobody can tell afterwards whether the design is good or merely the one you stopped on') and some restatement of 'a study keeps every point' are persuasive padding rather than information.

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 9-parameter orchestration tool with no output schema, the description compensates fully: it spells out the either/or return (finished table vs {job_id, status, points, pending}) and enumerates the result fields including per-point `ok`, band/state, cache_hit, and per-response aggregate stats. Nothing an agent needs to call or interpret it is missing.

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 coverage is only 11%, so the description must carry the load and it does: concrete JSON examples for `variables` (explicit values vs min/max/levels), `sampling` (grid default vs lhs with n_samples/seed), `responses` with `$variable`/`$handle` substitution, plus `recipe`/`fixed_inputs`, `objective` shape, and `max_points` default. Only `workspace` is left to the schema.

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 concrete verb+resource ('Sweep parameters over a sampled design space and record the WHOLE search as a table') and positions itself explicitly in the tool hierarchy ('the DOE primitive between the parametric layer and the solver catalog'). An agent can distinguish it from recipe/recipe_list/solve siblings without opening a schema.

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 explicit selection rules for its own sub-modes: grid is 'the only thing that can prove a trend' but cost is the product of level counts, while lhs should be used 'past 2-3 variables'. It also routes across tools: pass `recipe` to rebuild geometry per point, omit it to sweep against a fixed handle, and 'poll job_result for the completed table' when a job id is returned.

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