Skip to main content
Glama

Optimize Submit

optimize_submit

Searches bounded design variables or shape geometry to satisfy performance constraints, then reports whether the optimum is proven against measurement uncertainty.

Instructions

Vary parameters until the spec is met, then say whether it was PROVEN — the step that closes the design-to-spec loop.

Everything else in this family measures; this searches. Two things make it different from a generic minimizer, and both come from the performance-contract layer underneath it:

A constraint verdict has three states. indeterminate — the measurement's uncertainty band straddles the limit — is NOT a failed step. An optimizer that reads it as a failure walks away from good designs; one that reads it as a pass converges on unproven ones. During the search an indeterminate constraint is scored on its nominal value, so it neither attracts nor repels, and the winner is proved properly at the end.

Convergence is not proof. A simplex can settle on a point that clears its limit by 2 % while its own grid-convergence band is 5 % wide — noise with a favourable sign. proven is therefore reported separately from converged, and is True only when the final measurement has every constraint at pass and no margin swallowed by its own band.

variables must be continuous and bounded — {"name": "diameter_mm", "min": 5, "max": 25, "start": 10}. An optimizer without a box walks to values that satisfy the arithmetic and mean nothing physically.

objective and each constraints entry use the performance-requirement mapping ({tool, metric, conditions, limit, screen, band_pct}), with "$<variable>" in conditions carrying the candidate's value. tier='auto' searches cheaply on each block's screen estimator, then polishes on the real tool from where the screen landed; 'screen' or 'solver' runs just that leg.

The search is a bounded Nelder-Mead — derivative-free because there is no adjoint through a CFD solve — so every evaluation is a real measurement. budget ({max_evals, max_wall_s}, default 40 evaluations) is the ceiling; revisited points are served from cache and do NOT count against it.

Shape optimization. Pass a recipe (+ fixed_inputs) and it is rebuilt for every candidate, so the search varies GEOMETRY rather than only numbers — "$handle" in a response's conditions is that candidate's part, and the returned history carries the handle each point built. Pass handle instead to optimize parameters against one fixed part; pass neither and the search is purely parametric.

Geometry-driven candidates are built on the MAIN thread through the worker's work queue, because FreeCAD's document API is not thread-safe and this search runs as a background job. That queue is drained once per incoming request, so a shape search only advances while you are polling job_status/job_result — the poll you must do anyway is what gives it its turn. Poll at your normal cadence and it simply works; stop polling and it stalls rather than finishing in the background. A candidate whose recipe fails to build is scored out as an infeasible point, not an error. study_submit remains the right tool for a FIXED grid over recipe geometry, which needs no queue at all.

Returns {job_id, status}; poll job_result for {ok, proven, stop_reason, best_params, best_value, objective: {name, metric, sense, value, band_pct}, constraints: [{name, state, measured, limit, band_pct, margin, margin_pct, detail, trust_reasons?}], phases: [{tier, n_evals, best_params, best_value, converged, reason}], history: [{i, tier, params, value, score, feasible, cached}], n_evals, n_cached, budget, variables, warnings}.

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>",
      "objective": "<objective>"
    },
    "name": "optimize_submit"
  }
}

Input Schema

NameRequiredDescriptionDefault
tierNoauto
budgetNo
handleNo
recipeNo
objectiveYes
variablesYes
workspaceNoRun this call in this named workspace
constraintsNo
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?

With annotations already declaring readOnlyHint=false, openWorldHint=false, and destructiveHint=false, the description adds substantial behavioral context: indeterminate constraints are scored on nominal value during search, convergence is distinct from proof, budget/cache semantics are explained, and shape searches require polling because they use a main-thread work queue. It also clarifies that failed recipe builds become infeasible points rather than errors.

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 long but front-loaded and organized with bold sections for the most important non-obvious behaviors. Most sentences earn their place given the tool's complexity, though some repetition around polling and convergence could be tightened.

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?

There is no output schema, but the description enumerates the job_result return shape in detail, including proven, stop_reason, best_params, objective, constraints, phases, history, and warnings. Combined with the behavioral and parameter coverage, an agent has everything needed to submit and interpret the optimization.

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 only 11%, but the description compensates richly: it defines variables as continuous and bounded with an example, maps objective and constraints to performance-requirement fields, explains tier modes, documents budget as max_evals/max_wall_s with default 40 evaluations, and distinguishes recipe, fixed_inputs, and handle semantics. The workspace parameter has a schema description already.

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 first sentence states a specific verb and outcome: vary parameters until spec is met and report whether PROVEN. It explicitly differentiates this tool from the rest of the family ('everything else measures; this searches') and from generic minimizers. An agent can distinguish it from study_submit and other analysis tools without opening schemas.

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?

The description gives explicit routing rules: use study_submit for a FIXED grid over recipe geometry, use this for search; pass recipe for shape optimization, handle for fixed-part parameter optimization, or neither for purely parametric search. It also states the polling requirement for shape searches and clarifies tier behavior ('auto', 'screen', 'solver').

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