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

Annotations already declare destructiveHint=true and idempotentHint=false; the description then adds substantial behavior beyond that: invalid steps are rolled back with a stated reason, edits inside frozen_keep_mm are clipped and the clip is reported as a fact, splicing leaves triangles outside the edit zones bit-for-bit unchanged, allow_stale defaults to a no-op that only reports marks_match_final_stl false, and overwrite is required to reuse an earlier output folder. It also states that final.stl and the run folder are untouched, which is exactly the safety context the agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence front-loads the essential constraint (edit at marks, new folder, no verdict) and the reply-resource pointer is a useful shortcut. However, the body is a dense ~450-word block that interleaves parameter documentation with s7_cleanup method internals (closing balls, isotropic fairing, web fairing, tube rebuilds) in long parenthetical chains, making it hard for an agent to scan for the fields it needs. Every idea is relevant, but the packing and ordering cost readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must convey return behavior, and it does: it names the artifacts written (edited.stl, apply_marks.json), what the short vs detail reply contains, the reply resource topopt://replies/apply_marks for key meanings, and specific reply facts such as defaults_used, marks_match_final_stl, clip facts, and rollback reasons. It does not fully describe the shape of a successful short reply or the planned-volume/reach fields for tube smoothing, so a 4.

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

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

Schema coverage is 0%, so the description carries the entire burden, and it does document all 8 parameters: marks (path, JSON text, or object; version 1, mm, frame of final.stl), run_dir defaulting to the last run with its required files, out_dir default and its refusal cases, overwrite, detail, allow_stale, yaml_path. The options object is expanded with defaults (radius_scale 1.0, pitch_mm bounds, max_crop_voxels, frozen_keep_mm 3, parent_check modes, smooth_mode/remove_mode enums, per_mark precedence). Several option keys (max_total_voxels, close_mm, neck_min_mm3, parent_tol_mm, loose_body_mm3, max_odd_rays) are listed without meaning, which keeps this from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: edit the finished part at the marks of the Refine page, into a NEW folder. It also draws a boundary against FE-oriented siblings ("No FE run is made") and names cleanup_list as the producer of marks, so the agent can place it in the workflow. It stops short of naming the sibling to use instead of this one, so not a 5.

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

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

"No FE run is made: the stiffness and stress of the edited part are not known" tells the agent when this tool is and is not appropriate (i.e. it is not a substitute for run_topopt). It gives the step order (remove, then smooth, then add) and the refusal conditions for out_dir, which is usable guidance. There is no explicit "use this when X, use sibling Y instead" routing sentence, so a 4 rather than a 5.

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

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

Goes well past the annotations: writes to <work folder>/runs/<name>/, returns check and warnings itself, leaves files on builder failure with problems listing the errors, error shape is {ok:false, error} naming the key path, and a guard stop can freeze the machine if the memory estimate exceeds RAM. The idempotent/destructive hints are consistent with a spec-to-files build.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and usage are front-loaded, but the body is a dense wall of run-on sentences mixing tool behavior with exhaustive spec-schema detail (voxel-plane notes, mirror parity, spring stiffness units). Much of that content earns its place given 0% schema coverage, yet its organization makes it hard to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex spec-driven builder with no output schema, the description covers inputs, side effects, result keys, error shapes, guard-stop handling, and where further detail lives (topopt://replies/build_regions, spec.yaml). Nothing an agent needs in order to call it correctly appears to be missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does: it documents the `name` default (spec["name"]) and expands `spec` in depth — regions, primitives, load_cases, material, settings, units (mm, N, MPa), volume_fraction vs target_mass_g mutual exclusion, mirror/springs/joints/fixed_axes. An agent could construct a valid spec from this text alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and two concrete artifacts ('Build region STLs and a problem YAML from a part spec given as data'), and the second sentence pins down the triggering condition (user describes a part in words). Named siblings (check_problem, run_topopt, find_features) make its position in the pipeline unambiguous.

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

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

Explicit routing: use it when the part is described in words, call check_problem only after editing the YAML or for the agent's own STLs, then state assumptions and go to run_topopt. It also gives a decision rule for missing load data (ask before the run) and a recovery procedure for a guard stop.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description explains nuanced behavior: what counts as stale, that comment/format/method-setting changes are facts rather than staleness, how run staleness differs, and what gate means. This gives an agent substantial context for interpreting results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, and the remaining detail is dense but relevant to interpreting the returned status fields. It is appropriately sized for a status tool with no output schema, though the second paragraph is quite packed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must explain the return semantics, and it does: brief_stated, stale_files, inputs, runs, per-run stale state, and gate are all defined with enough context to interpret them. For a complex case-status tool, this is complete enough for an agent to call and understand it.

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

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. It identifies yaml_path as the problem YAML and adds the important path-resolution rule that relative paths start at the work folder, which is meaningful beyond the bare string schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource: shows the status of a problem YAML case, including brief, input hashes, earlier runs, and staleness. It explicitly says it changes nothing, and the scope is clearly case-level rather than run-level, distinguishing it from siblings like run_status.

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

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

The description implies when this is useful by enumerating case-level status fields and noting that it changes nothing, but it does not explicitly say when to use this instead of run_status, show_problem, or other status tools. Usage is inferable but not routed with alternatives or exclusions.

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

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

Adds substantial context beyond the readOnly/idempotent annotations: the auto-solver path spawns a child process for a self-test bounded at 60 s (longer the first time per device/driver, then cached), and it distinguishes blocking warnings ('settings.solver is' → run_topopt will stop) from non-blocking ones ('fact: settings.iterations' → grey design, not blocking). Error shape on bad input is disclosed. The account of caching and child-process cost is slightly garbled, so not a clean 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, which is good, but the body sprawls across loosely related topics (solver selection, warning prefixes, reply keys, fine_pass internals) with at least one malformed sentence ('seconds the first time on a device and driver'). Length is partly justified by the tool's complexity, but the structure does not help an agent scan it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, and the description does cover the return shape at a high level (facts, estimates, warnings; ok:false + error), plus specific keys it knows matter (lost_force, fine_pass). It delegates full reply-key meaning to topopt://replies/check_problem, which is a reasonable pointer but leaves the description alone insufficient for interpreting the payload.

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

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

The single parameter has 0% schema description coverage, but the description supplies the semantics that matter: yaml_path is the problem YAML and relative paths resolve against the work folder. That is exactly the ambiguity an agent would otherwise hit. The surrounding solver/GPU settings discussed are YAML keys, not parameters, which adds a bit of noise.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb chain and resource: 'Load and voxelize a problem YAML', and immediately scopes it with 'no optimizer run'. The sibling boundary with run_topopt is drawn explicitly ('Use it before run_topopt'), so an agent can pick between validating and running 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.

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

Gives clear workflow placement: call it before run_topopt, and it is also valid for the user's own YAML and STLs. It clarifies that settings.solver is not a run_topopt parameter, which prevents a real misuse. No explicit 'do not use when' case is stated, keeping it below a 5.

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

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

Annotations only flag destructive=non-idempotent write; the description adds a great deal more: it writes marks.json and cleanup.json into a brand-new folder, never touches the run folder or inputs, and refuses existing/ratchet-root/symlink/non-cleanup folders with the reason and options. It also discloses runtime (~2 s / 8 s), that the call completes server-side even if the client stops waiting (Codex 60 s), recovery via cleanup.json or overwrite=true, the memory/voxel-limit fallback instead of a crash, and the error envelope {'ok': false, 'error': ...}.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and the safety-critical refusal rules are front-loaded, and nearly every line carries real information (defaults, reply keys, recovery paths). But the body is a wall of telegraphic fragments and parentheticals ('CONTRACTS.md section 29.3', 'the marks: source of ratchet_run read it'), with no headings or grouping, so parameter facts, detector lists and failure modes interleave and are hard to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description enumerates the reply keys (ok, counts, candidates with their fields, applicability, bodies, estimate, routes, problems, notes, out_dir_rel, marks_rel, report_rel) and the error shape. For a destructive, write-producing tool with 8 undocumented parameters, it covers everything an agent needs to call it safely and interpret the result.

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

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 all semantics — and it does, documenting every one of the 8 parameters: run_dir and its default (last run of this server), out_dir and its default plus the refusal cases, estimate_only, overwrite, detail, yaml_path, root, and the full options set with defaults (pitch_mm 0.5, max_candidates 10/null, kinds, order, max_voxels, max_gb, spur_*/bump_*/member_*/mild_*, web_flatness, opening_radius_mm, frozen_*). It even notes which constants are not settable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb, resource and artefact: list geometric cleanup candidates of a finished part as a marks file in a NEW folder. It explicitly separates itself from siblings by stating 'The list judges nothing: ratchet_run(marks=marks_rel) applies each mark and judges it' and by naming the marks format consumed by apply_marks/the Refine page. An agent can tell this apart from ratchet_run and apply_marks without opening any schema.

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

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

It states the precondition (a finished run needing run.json, labels.bin, result/final.stl), the branch where a loose body exists ('judge them, then list the acc_01 of that ratchet root'), the follow-up tool (ratchet_run with marks_rel), and a cheap pre-flight mode (estimate_only: no search, no file). What it lacks is a crisp 'do not call this when…' list, and the guidance is embedded in dense prose rather than stated as routing rules.

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

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.

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.

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.

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.

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.

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.

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

The description flatly asserts "Changes nothing" and "installs and builds nothing", while the annotations declare readOnlyHint=false. It also discloses that the OpenCL device list and self-test run in a child process with a 60 s limit, an action with real cost that the 'changes nothing' framing hides from an agent deciding whether to auto-approve. The rest of the disclosure (gpu-mg failure modes, case C behavior, env vars) is rich but does not cure this conflict.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The first three lines are well front-loaded, but the remainder is a wall of deep solver internals — pocl and Intel Arc measurements, revision 133e5a1, residual values, harmonic columns, gpu_tol/gpu_backward_error tuning — that an agent does not need in order to call this tool or read its reply. Much of it reads as release notes rather than tool guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does try to cover returns: reply key resource, the meaning of `recommendations` (reason, command, license_note, speedup_factor), and the distinction between a fact (`gpu_solver`) and an offer. But it never states the actual shape of the top-level reply or the units/format of the time estimates, and the bulk of the text is tangential to correct invocation.

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

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

Schema coverage is 0% and the single parameter is bare in the schema, so the description must carry it — and it does: yaml_path is optional, relative paths resolve from the work folder, and passing it changes the reply so `problem` holds per-backend time estimates. That is meaningful semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line states a specific resource and scope: facts about this machine and the solver backends, with an explicit "Changes nothing" non-goal, reinforced by "Use it to answer 'can this machine run it, and how fast?'". It is clearly distinct from problem-oriented siblings such as check_problem/show_problem, though it never names them.

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

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

It gives two concrete triggers (answering 'can this machine run it, and how fast?' and 'before a long run') plus a negative boundary ('installs and builds nothing ... if the user agrees, you run the command'), which is a real routing rule. It never names an alternative sibling for the case where the user wants a specific problem validated instead.

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

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

Annotations declare mutation, non-idempotent-looking write, and destructive=true, but the description adds far more: the call is synchronous and can block for minutes, concrete cost ranges in faces/MB/seconds/RAM, the fact that an existing .step/.stp is replaced while other existing files error, and that a failed check still writes the file with exit_code 3. These are behavioral facts an agent cannot derive from the annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and scope, and nearly every sentence carries operational information. The cost paragraph is somewhat over-detailed—three separate benchmark anecdotes (9k–36k faces, 85k faces, 356k faces) could be compressed to a range plus the note that cost scales with face count—which costs some scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates by enumerating the report fields (input, settings, build, model, volume, deviation, checks, timing_s, peak_rss_bytes) plus the two failure reply shapes. Combined with 7 fully explained parameters and the cost model, an agent has everything needed to invoke, budget, and interpret this tool.

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

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

Schema description coverage is 0%, so the description carries the entire burden and does: it defines run_dir defaults and path resolution, out semantics and where the report lands, part_only's effect on input/output filenames, tolerance_mm's meaning (largest surface move in mm), its default derivation (voxel size / 20), and its edge case (removing every triangle is an error), plus merge_planes and schema (AP214/AP242 aliases) and estimate_only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ("Write a faceted STEP file of a finished run") plus an explicit scope restriction ("Post-only: no pass runs and no input file changes") and a CLI equivalence ("Same as `topopt step`"). An agent can distinguish this from a STL/other-format export or from run_mesh/verify_run siblings without reading the schema.

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

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

Gives an explicit recommended workflow ("Call it with estimate_only first for a large mesh") with the reason (the estimate gives time before work starts), states the precondition (a finished, post-processing run), and states exclusions (no pass runs, no input file changes, existing non-.step files give an error). That is when-to-use, when-not-to-use, and a prerequisite in one place.

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

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

Goes well beyond the annotations by detailing return structure (holes, bosses, flat_faces, mesh, method, facts), timing, error format, limitations (open mesh still returns what can be found, no repair), and the exact integration with build_regions. This is rich behavioral context that helps an agent understand what to expect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a long, dense block of text with many technical details and references to external documentation (CONTRACTS.md sections). While the information is useful, it is not front-loaded or well-segmented, making it harder to scan quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the output and the absence of an output schema, the description thoroughly explains all return fields, error behavior, and usage in downstream tools. It leaves little ambiguity about what the tool does and how to interpret its results.

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

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

The single parameter stl_path has no schema description, but the description compensates by explaining that a relative path starts at the work folder and that it must be an STL file. This is sufficient for a 1-param tool, though not extensive enough for a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'List the holes, bosses and flat faces of an STL file'. This clearly distinguishes it from all sibling tools, which deal with runs, regions, materials, etc., not feature extraction from an STL.

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

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

Provides clear context: it is read-only, mentions the time cost for a million triangles, describes error behavior, and explains how the output is used with build_regions. It also notes limitations (fillet-joined, tapered holes, slots are not detected) but does not explicitly state when to prefer it over alternatives—though none exist among siblings.

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

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

The annotations already declare read-only, non-destructive behavior, but the description adds substantial behavioral context: case/punctuation/maker-name normalization, ambiguous-family handling, `user_file` problem isolation, null-value semantics, derivation rules for `material.filament`, and the caveat that data-sheet values describe printed test bars rather than the user's part. No annotation contradiction is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is front-loaded with purpose and usage, and most content earns its place because there is no output schema and the return statuses are complex. It is still dense prose for a one-parameter lookup, with a long inline listing of return fields that could be more scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and a single undocumented parameter, the description supplies the missing return semantics, statuses, derived-value behavior, user-file behavior, and follow-up tool guidance. Together with annotations covering safety, an agent has enough information to call and interpret the tool correctly.

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

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

The schema has 0% description coverage for the single `name` parameter, so the description must carry the full burden, and it does. It explains that the product is taken as the user says it, that case, punctuation, maker name and 'my' do not matter, and that a family alone yields an 'ambiguous' result.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it finds a 3D printing filament by name in the shipped catalog and the user's `topopt-filaments.yaml`. It also distinguishes the tool from write operations by saying 'It reads; it changes nothing' and later names related tools such as `save_material`, `printer_materials`, and `check_problem`.

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

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

It gives an explicit trigger: 'Use it when the user says which spool they have ... before you ask for a modulus or a density.' It also explains what to do on ambiguity ('Ask the user which one; do not pick for them') and on no match (look up the data sheet and `save_material`, or ask the user), so when-to-use and next alternatives are clear.

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

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

Beyond the readOnly and idempotent annotations, it discloses matching behavior, how ambiguous and no-match cases are returned, what to do when the user file has problems, and how the shipped catalog remains usable. This is unusually rich behavioral context for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, usage, and parameter semantics before detailing return behavior. It is lengthy, but most detail is justified because there is no output schema; the return field inventory and profile field explanation are dense but useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema, the description covers matching semantics, all three result modes, user-file edge cases, and recommended next steps. An agent has enough information to call it correctly and interpret the response.

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

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

Schema description coverage is 0%, so the description carries the full burden for the single name parameter. It explains that the name is the model as the user says it, that case, punctuation, maker name, 'my' and 'printer' are ignored, and gives concrete equivalent examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Find a 3D printer by name' in both the shipped catalog and the work folder's user printers file. It also explicitly says the tool only reads and changes nothing, which separates it from mutation-oriented siblings such as save_printer.

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

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

It gives a clear trigger: use this when the user names their printer, before asking for bed size or process. It does not explicitly state when not to use it or name a competing lookup alternative, but the usage context is strong.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add operational detail — and it does: result ordering (newest first), the fields surfaced (state and iteration), and the exact criterion that makes a folder a run. It stops short of describing the full return shape or what happens with an empty/nonexistent work folder.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and ordering, followed by the one definition an agent actually needs. No filler or restatement of the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must convey the return content, and it names the salient fields (state, iteration) and ordering. A little more on the record shape (e.g. whether the folder name/path is included) would make it fully self-sufficient for a zero-param listing tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description still adds useful framing by clarifying that any paths in the results are relative to the work folder, which preempts a likely agent misreading.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the run folders in the work folder') and then defines the ambiguous term 'run folder' by its detection criterion (status.json or run.json). An agent can tell this apart from run_status, run_result, or run_history without opening any schema, since this is the enumeration tool.

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

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

The ordering note ('newest first') and the folder-detection rule imply the discovery use case, but the description never says when to choose this over siblings like run_history, run_status, or compare_runs. Usage is inferable rather than stated.

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

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

The annotations already declare a non-idempotent, destructive write operation, and the description adds substantial context beyond that: it writes only into a new folder, refuses specific out_dir locations, copies original region STLs, leaves the input YAML/run/region STLs unchanged, and documents overwrite behavior. It also explains overlap handling, file-order precedence, and which mark fields are ignored.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and scope, then proceeds through behavior, workflow, reply keys, parameters, and mapping in a logical order. It is long and dense, but most of the length is justified by seven undocumented parameters and complex refusal/default behavior. Some sentences could be tightened, but the structure is appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must explain return behavior, and it does: it identifies reply keys via `topopt://replies/marks_to_hints`, describes `detail` versus `hints.json`, and explains that invalid out_dir replies name the offending fact and options. Combined with the parameter semantics and safety constraints, an agent has enough context to call and interpret the tool correctly.

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

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

With 0% schema description coverage, the description fully compensates by documenting all seven parameters: accepted forms for `marks`, run resolution for `run_dir`, default and contents of `out_dir`, `detail`, nested `options` keys and defaults, `overwrite`, and fallback behavior for `yaml_path`. This adds essential meaning that the bare schema does not provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it turns Refine-page marks into facts, options, and a proposed YAML in a new folder. It also explicitly scopes the operation as editing no mesh and distinguishes the output folder from the run, which lets an agent separate it from siblings such as apply_marks and run_topopt.

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

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

It gives clear workflow guidance: after the call, check the report, then run_topopt with the proposed YAML and compare_runs. It also explains the agent can read the report, change `options` and call again, or edit the YAML. It does not explicitly name when to use this instead of `apply_marks` or other mark-related siblings, so it falls short of full when/when-not/alternatives coverage.

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

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

Annotations already declare read-only/idempotent, but the description adds real behavioral context they cannot: strict-gate semantics (exit_code 4, override path, 'No run stops on it'), the 'failed check is data, not an error' contract, the {

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and each parameter gets its own block, so it scans well for its size. It is long and dense with backticked jargon, and the check/coverage documentation at the end runs together, but with no output schema most of that is load-bearing rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description documents the return payload itself: per-check fields (id, state, reason, value, limit with source, method), the nine check names, the summary/settings/input/timing_s/definitions block, and the partial/coverage failure model. Nothing material is left for the agent to discover empirically.

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

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 all five parameters, and it does: path resolution rules and defaults, print_settings example dict with concrete keys, resolution_mm meaning (voxel size vs 0 for exact CAD) plus its default, and strict's opt-in semantics. The YAML/settings/option precedence order is exactly the detail an agent needs to call this correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Check a finished part for printing') plus an explicit scope boundary ('Geometry only: no solve, no run') and an equivalence anchor ('same report as `topopt printcheck`'). That cleanly separates it from run_topopt, run_result and verify_run in the sibling list.

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

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

States when the tool is not needed ('A finished run already has this report as result/print_check.json (run_result shows its counts)') and when to re-invoke it ('call this tool again for other limits or another direction'). It also resolves the input-precedence questions an agent would otherwise guess at (print_settings wins over YAML; a run folder supplies the print block).

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

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

Annotations already declare read-only/idempotent, but the description adds real value beyond them: the error shape {"ok": false, "error": ...} when no printer can be resolved, the fact that no run is refused because of a state, the ~70-item reply size with advice to read only relevant groups, and the not_used / older-sheet handling. Nothing contradicts the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then parameter, then state definitions, then return shape — a sensible order. It is dense and long, with heavy backtick notation and parentheticals, but nearly every sentence carries decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description enumerates the return fields (ok, printer, catalog_version, counts, groups, available, user_file, note) and the per-item shape (id, name, family, origin, available, source, reasons). Combined with annotations covering the safety profile and the state taxonomy, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 0% and the single parameter is undocumented in the schema, so the description carries the full burden — and it does: accepts a name or id, points to find_printer for naming, and defines the fallback to print.printer_model in the preferences file with the resulting error behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific user question ('Which filaments can this printer print?') and states the resource and scope precisely: every catalog and user-file filament, grouped by state, with reasons. It is clearly distinguishable from catalog-search siblings like find_material, which it explicitly routes to for unlisted filaments.

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

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

Gives clear usage context and alternatives: use find_material then save_material for a filament that is not listed, and see find_printer for how to name a printer. It also defines the default behavior when the printer argument is omitted. It does not state an explicit 'do not use this when...' case, so it stops short of a 5.

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

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

Annotations declare destructiveHint=true and idempotentHint=true; the description adds real value on top by explaining what gets destroyed (decline drops the candidate), that the decision is written to the log as owner_approval, and that it does not start a job. The one gap is that it doesn't restate reversibility beyond the drop semantics, but the destructive edge is well covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core decision semantics, then organized into labeled lines for each parameter and the reply. Dense but every line adds information; a small amount of prose could be tightened, but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by enumerating the reply fields (ok, id, owner_approval, promoted, parent), including that promoted may be null. Combined with the workflow precondition and follow-up, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: root is defined with its default (last ratchet this server started), id is defined with an example format (c003) and its default (the waiting one), and decline is defined as drop-instead-of-promote. All three parameters gain meaning beyond their bare schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: the owner gate that promotes or drops the accepted candidate that is waiting. It is immediately distinguishable from ratchet_run and ratchet_status, both of which it references by name.

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

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

Explicit about the precondition (a ratchet started with stop_before_promote or acceptance.owner_gate), what status shows it as (pending / waiting_for_owner), that the user must be asked first, and the follow-up action (call ratchet_run again with the same root). No inference required.

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

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

Annotations declare a destructive, non-idempotent, non-read-only write, and the description goes well beyond them: the start run writes nothing, a real start returns immediately because a detached process does the work, a second call with the same root resumes rather than restarts, overwrite relocates old files into earlier_NN, and override_lock bypasses a held job lock. It also documents side-effect details annotations cannot express, such as `errors.verify` and `no_input` on refused surfaces.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and default workflow are front-loaded, and each subsequent block maps to real parameters, so little is wasted. However, it is a dense run of unbulleted prose paragraphs, and a scannable list for the dozen parameter semantics would make it easier to extract the right flag under time pressure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter, destructive, long-running job with no output schema and zero schema coverage, the description covers the call ordering, async nature, resume/conflict behavior, promotion output fields, and error shape ({"ok": false, "error": ..., "exit_code": 1 or 2}). An agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema coverage is 0% with 12 parameters, so the description must carry the full burden — and it does, defining run_dir requirements, the two `source` forms (`marks:FILE`, `stl:FOLDER`), root defaults and resume semantics, what each of rebaseline/overwrite/override_lock/stop_before_promote/max_candidates/mesh_size_mm does, and the estimate_only default. Almost every parameter gets semantics the schema cannot supply.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource — 'judge candidate edits of a finished part and keep the ones that pass' — and immediately defines the mechanism (baseline parent, promotion to acc_NN, failures logged). It is clearly distinguishable from ratchet_status (watching) and ratchet_approve (promoting), which are named later.

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

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

It explicitly prescribes the default workflow — estimate_only defaults True, 'Tell the user the numbers, then call again with estimate_only=false,' then 'call ratchet_status to watch it' — and names the alternatives for conflicting roots (new root, rebaseline, overwrite). It also states the concurrency constraint ('Only one job goes at a time on this machine'), so the agent knows when a call will block or conflict.

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

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

Goes well beyond the annotations: it discloses that final states appear only after the process ends, that the next call is therefore not refused as busy, that nothing calls back at job end so polling in the current turn is mandatory, and that a promise of a later report cannot be kept. It also explains failure diagnostics (last_error exit code, log_tail for killed processes) and the skipped partial line in log_facts. This is a rich behavioral contract that annotations alone could not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, but the body is one dense block where the state enumeration, polling loop, and return-field list are interleaved, and the trailing 'Also:' sentence lists return fields after the behavioral advice. The content mostly earns its place, but the run-on state definitions and lack of grouping make it harder to scan than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description takes full responsibility for return values and does so completely: every state name, the job facts, process_alive, pid, mesh_size_mm, baseline, and log_facts. An agent has everything needed to call it and interpret the result without further documentation.

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

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

Schema coverage is 0%, so the description must carry both parameters, and it does: 'root' is defined as the ratchet folder with its default (the folder of the last ratchet this server started), and 'last' is defined as how many trailing records to show, with each record's fields spelled out (id, decision, failed rules, reasons, promoted, owner_approval). It even points to ratchet.jsonl as the underlying log.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Show the state of a ratchet') and immediately enumerates what is shown: counts, current parent, last records with reasons, and the job. This clearly separates it from ratchet_run (which starts a job) and ratchet_approve (which decides), even though neither sibling is named as the explicit contrast.

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

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

Gives explicit operating instructions: 'call it again in this turn until the state is finished, waiting_for_owner, baseline_failed, stopped_after_approval or failed, or process_alive is false', and names ratchet_approve/ratchet_run as the next calls to make. What's missing is a plain statement of when to prefer this over case_status or run_status, but within the ratchet family the routing is unambiguous.

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

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

With destructiveHint=true already declared, the description still earns its place by naming the two files written (<yaml stem>.case.json and <yaml stem>.case-log.jsonl) beside the YAML, saying the brief is replaced rather than duplicated, and disclosing what is fingerprinted (SHA-256 of YAML and region files, method key values). It goes further to explain staleness propagation to case_status and run_topopt, and the deliberate exception that method-setting changes are facts, not staleness. That is substantial behavior beyond the annotations and no contradiction with them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence and the per-parameter block is well organized. It is on the long side, though: the brief_facts method-key aside and the 'you can report it' tail add words without changing how the agent calls the tool, and one clause ('say that the brief is stale and name it') is slightly clipped.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating tool with 0% schema coverage, four parameters, no output schema and only hint-level annotations, this covers everything an agent needs: what is written, where, what replaces what, all four parameter meanings, path edge cases, and how the result feeds later checks. Nothing essential is left dangling.

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

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

Schema coverage is 0% and all four parameters are undocumented in the schema, so the description carries the full load — and does. yaml_path gets its work-folder constraint and edge cases, text gets its expected content (goal, loads, mounting, material, critical sizes), assumptions gets the {text, origin} shape with the three origin values user/inferred/default spelled out, and criteria is noted as optional with 'same form.' That is meaning the schema cannot supply, since its items are just additionalProperties:true objects.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first line gives a specific verb and resource — record the brief of a problem YAML — and scopes it to 'what the user wants and the assumptions that you state.' It then defines the case concept and names the sibling tools that consume the brief (case_status, run_topopt, brief_facts), so an agent can tell exactly where this fits among 30 siblings.

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

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

It says when the call creates a case versus replaces a brief, what happens for a YAML outside the work folder (no case file, reply gives facts and options), and what a source-checkout YAML gets. It also states the downstream consequence — run_topopt returns awaiting_user with an override when the brief is missing or stale. What it does not do is tell the agent when to prefer this over a sibling first step (e.g. check_problem or show_problem) before recording.

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

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

Annotations declare destructive, idempotent, and non-read-only behavior, and the description explains why: later renders overwrite PNGs with the same names, out_dir redirects output, and same input yields same PNG bytes. It also adds timing, memory estimates, inline-vs-disk output behavior, and facts about mesh validity, going well beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but dense and front-loads purpose and usage before parameter details. Some sentences pack multiple concepts, such as view syntax and section-cut behavior, which slightly hurts readability, but the length is justified by 12 undocumented parameters and complex output behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers input modes, parameter formats, defaults, return shape, PNG overwrite behavior, view and section semantics, color conventions, performance limits, and mesh failure facts. With no output schema and zero schema descriptions, this is complete enough for an agent to call correctly.

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

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

Schema description coverage is 0%, but the description explains all 12 parameters in prose: stl_paths/run_dir/yaml_path input precedence, roles, views syntax, section syntax, regions modes, size, max_triangles, loads, inline, and out_dir defaults. This fully compensates for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Render a part to PNG images so you can look at it,' and adds that no display or GL is needed. It distinguishes the tool from run/verify siblings by framing it as visual inspection before and after a run.

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

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

Gives explicit timing guidance: 'A look before the first run and after each run finds a wrong region or load fast,' and notes YAML renders can be shown to the user to check force directions before a run. It does not explicitly name sibling alternatives to use instead for numeric or status checks, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds real context beyond them: missing or partial files surface as facts in `problems` rather than errors, the scan caps at 5000 folders and reports it, and `limit` truncation is announced via `count`. It also warns that `yaml_newer_than_run` means the YAML may not be the one that ran.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then structured per-parameter. It is fairly long because there is no output schema and it enumerates every returned field, which earns most of its space, but the field list is dense enough to border on reference-doc dumping.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so documenting the return shape is necessary and the description does it field by field (name, run_dir, state, settings, metrics, metrics_source, problems). Combined with the parameter and edge-case coverage, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: root (relative paths resolve from the work folder, default), depth (default 2, max 5, what makes a folder a run folder, run-folder root shortcut), limit (default 20, 0 means all, count semantics), and detail (what extra is included). This is more than the bare schema types convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('facts of earlier runs under a folder, newest first, read from files on disk') and explicitly differentiates itself from the sibling list_runs ('the cheaper list, it reads no metrics'). The agent can pick between run_history and list_runs without opening either schema.

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

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

'Use it to see what was tried: state, YAML, key settings, main metrics' gives a clear usage context, and the closing sentence names the cheaper alternative list_runs with the tradeoff. It lacks an explicit 'do not use this when...' exclusion, for example versus compare_runs or run_status, so it stops short of the top band.

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

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

Rich disclosure beyond the annotations: stopped runs return `done: false` and `stopped: true`, verify-derived fields are re-read on every call, and reply key meanings live at topopt://replies/run_result. It does not explain why annotations mark this a non-read-only-but-idempotent operation, so the side effect implied by readOnlyHint=false goes unaddressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Core purpose and units are front-loaded, which is good, but the body drifts into a multi-step recipe for re-running run_topopt with settings.part_only_min_film_mm, which is workflow guidance rather than this tool's contract. The telegraphic run-on phrasing makes the thin-film and stress paragraphs hard to parse on a first read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden and meets it: shapes for successful and stopped runs, units, the key-documentation resource, thin-wall field semantics, and the distinction between relaxed optimizer stress and verifier P2 p99.9. An agent has enough to interpret the reply correctly.

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

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

Schema coverage is 0%, so the description must carry both parameters, and it largely does: run_dir is the run folder defaulting to the last run this server started, and preview adds mesh facts plus ASCII silhouettes. The run_dir path format (absolute vs relative to the YAML) is still not spelled out.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and a concrete payload: final metrics, path of final.stl, and a text preview, gated on the run being done. It also names the sibling that does something different (render_part for real images) so an agent can separate the two 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.

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

Gives clear conditions: call when the run is done, preview=true only for clients that cannot open files, render_part for actual images, verify_run for the independent stress check. It never explicitly contrasts with run_status, so the boundary between 'status' and 'result' 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.

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond them: immediate return, no callback, process_alive semantics, stale_lock, stopped-state behavior, checkpoint continuation, verdict availability, and failure/log_tail details. It does not contradict any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and polling guidance, then moves into field-level return semantics. It is unusually long and dense, but because there is no output schema, most of the detail about state, checkpoint, verdict, and failure fields earns its place. Slightly better chunking or bullet structure would improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex status tool with no output schema, the description is complete enough: it covers polling behavior, state meanings, checkpoint/verdict fields, failure details, fine_run, and time_left. Given the single optional parameter and rich read-only annotations, an agent has what it needs to call and interpret the tool correctly.

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

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

The schema has 0% description coverage for the single run_dir parameter, so the description must compensate. It explains that run_dir is the run folder and gives its default as the last run started by this server, which is the key semantic an agent needs for an optional path parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource: showing the state of a run, including status, last iteration, and summary. It also distinguishes the tool from siblings by naming stop_run, run_topopt, and run_result in context. An agent can tell this is the monitoring/status tool rather than the result or stop tool.

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

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

The description explicitly says to call it again to watch a run, that each call returns immediately, and exactly when to stop polling: done, error, stopped, or process_alive false. It also warns that nothing calls the agent back and says to end the turn and tell the user what to ask for the result. It names stop_run and run_topopt resume as related actions, giving clear alternatives.

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

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

Annotations say destructive and non-idempotent; the description earns that with concrete consequences: without resume, a folder holding a checkpoint of an unfinished run loses it, a live lock names pid and start time, resume drops history and snapshots, changed inputs yield an error and nothing is written, and stop_run runs continue without allow_changed_inputs. It also discloses the no-callback model ("Nothing calls you back when the run ends") and that a killed run resumes bit-equal, which no annotation conveys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Strongly front-loaded: purpose and the no-callback constraint come first, then per-parameter notes, then the YAML-change policy. It is long and dense with parenthetical asides, and a couple of sentences (the bit-equal resume claim, where the lost force is reported) are marginal. Nearly every other sentence carries operational weight, so the length is largely justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter, destructive, long-running background job with no output schema and no schema descriptions, the description still covers start conditions, reply contents (assumptions, derived, earlier_checkpoint, continue, resume.facts), failure modes (lock, missing/stale brief, changed inputs), and restart semantics. It points to named resources (topopt://replies/run_topopt, topopt://levers) for lookup detail.

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

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

With 0% schema coverage across 14 params, the description carries the burden and does so for most of them: yaml_path (relative to work folder), out_dir (default runs/live, checkpoint-loss caveat), override_lock, proceed_without_brief, resume, continue_from, more_iterations, allow_changed_inputs, stop_rules. The five fine-pass params are only named and deferred to the topopt://replies/run_topopt resource, so fine_tol, fine_voxel and fine_passes still lack meaning here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Start a topology optimization run") plus the execution model ("in the background. Returns at once"), which is the fact an agent most needs. It also distinguishes itself from the siblings it hands off to (run_status to watch, run_result when done), so it is not confusable with list_runs, run_status or run_result.

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

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

Explicit preconditions ("Use after check_problem and after you state your assumptions to the user. If the user gave no load ... ask first") and explicit follow-up routing (run_status, run_result). It also gives when-to-use rules for the tricky modes: resume vs continue_from ("add passes to a run in a NEW run folder"), override_lock, proceed_without_brief, and allow_changed_inputs.

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

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

Goes well past the annotations: it discloses that only that file is written, that the file is re-read on each call so entries are live immediately, that the same id replaces a user entry while shipped ids/aliases are refused with a suggested alternative, and that other entries are untouched. It also specifies the success payload (ok, path, profile, created, replaced, note, problems) and the error contract (`{"ok": false, ...}` writes nothing, invalid YAML is left unchanged) — consistent with destructiveHint=true and idempotentHint=true rather than contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, usage ordering, and the unknown-value policy before the field specification, and almost every sentence earns its place given the empty schema. The optional-field enumeration is a dense run-on list, which hurts scanability but is unavoidable without machine-readable property descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write tool with a single untyped nested object, no output schema, and annotations that only flag destructiveness, the description supplies everything needed: trigger, user-consent step, full field contract, source-provenance rules, validation behavior, replacement/refusal semantics, and return shape. Nothing material is missing.

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

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

Schema description coverage is 0% and the single `profile` parameter is a free-form object with no property documentation, so the description carries the entire burden — and does: required keys (id slug format with example, maker, product, family, source_url or source "user"), run-required quantities (modulus via E_xy/E_z or bending modulus, density in g/cm3), and an enumerated optional set with units, ranges, enums, and semantics for every field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening states a specific verb, resource, and destination: keep a filament absent from the catalog, with facts and sources, in `topopt-filaments.yaml` in the work folder, and scope-limits it to that one file. It is clearly distinguishable from the sibling `find_material` (which is the lookup it follows) and from `save_printer`/`save_preferences`.

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

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

Explicit trigger and precondition: "Use it after `find_material` says 'none'", plus a prescribed procedure (look up the maker's data sheet, show values with the page address, call after the user agrees). It also names the alternative path for unknown values and the refusal cases (shipped id / shipped alias) with the required remedy.

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

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

Adds substantial behavior beyond the annotations: key-by-key merge semantics, null removes a key, {} removes a section (outputs too), unknown keys persist, and calling with no section creates an empty file. It also discloses error behavior (wrong name/key/value returns ok:false and writes nothing; invalid YAML or unwritable folder is refused) and the return field list, which is consistent with destructiveHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the write-scope warning are front-loaded, and the length is justified by 0% schema coverage and five sections. Some lines are heavily telegraphic ('`run_topopt` and `check_problem` fill nothing'), which costs clarity at the margins.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers inputs, merge/removal semantics, error cases, refusals and the return keys for a tool with no output schema and no parameter documentation. Minor gap: return fields such as kept_not_used and note are listed but not explained.

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

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

Schema coverage is 0% and every parameter is an untyped additionalProperties object, so the description carries the entire burden and does: it enumerates print (printer_model, printer_type, bed_mm, build_direction, self_supporting_angle_deg), material (E, nu, density, filament, name), filaments.available, quality.voxel_size, and outputs.renders/step/verify, including units and the rule that min_wall_mm is refused in print.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: it keeps the user's answers (print bed, material, filaments, quality, outputs) in `topopt-preferences.yaml` in the work folder, and pins the scope with 'It writes only that file.' An agent can distinguish it from mutating siblings like save_printer/save_material by the fact that it persists per-user run defaults, though it never names those siblings explicitly.

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

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

Gives clear timing ('Use it once, after the user answered') and a strong non-obvious caveat: a preference does not change a run by itself, since run_topopt/check_problem fill nothing and build_regions only takes a value the spec lacks. It also directs the agent to `environment` to inspect the file and notes there is no CLI equivalent. It stops short of explicitly naming the alternative save tools, so not a full 5.

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

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

Annotations flag the write and its destructiveness but say nothing about blast radius; the description supplies that (only `topopt-printers.yaml` is touched, other entries stay). It also discloses idempotent replacement ('the same id replaces a user entry'), refusal rules for shipped ids/aliases, validation against the shipped-catalog rules, and the no-write failure mode — all consistent with destructiveHint=true and idempotentHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and write target, then usage sequence, then field spec, then return/error behavior — a sensible order. It is dense and long for a one-parameter tool, but the length is mostly justified by the undocumented profile schema; a few lines (e.g. 'There is no CLI command: edit the file.') are instructional plumbing rather than tool behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one nested free-form object, no output schema, and mutation semantics, the description covers everything an agent needs: preconditions, per-field validation, collision/refusal behavior, the returned fields (ok, path, profile, created, replaced, note, problems), and the two failure modes (bad argument, invalid YAML) with the guarantee that nothing is written.

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

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

Schema coverage is 0% and the single `profile` parameter is a free-form object with no documented properties, so the description carries the entire burden — and does: required keys with formats (id slug, printer_type enum, bed_mm as [x,y], source_url or 'user'), the full optional set with value constraints ('heated'-only chamber_max_c, nozzle material enum), and null-means-unknown semantics plus field_sources.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: keep a printer that is not in the catalog, into `topopt-printers.yaml` in the work folder. It also scopes itself ('It writes only that file') and implicitly separates itself from `find_printer` (the lookup it follows) and `save_material` (a different file).

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

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

Explicit trigger and sequence: use it after `find_printer` says 'none', look up the maker page, show the user the values with the page address, and call only after the user agrees. It also states the negative rule for missing values (stay null, ask, do not guess).

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description still adds substantial context beyond them: that no optimizer runs, that behavior depends on the client (MCP Apps card vs. text-only fallback with just region counts and estimate), the interaction contract for the 'Start the run' button, and the concrete error shape {"ok": false, "error": ...}.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening and closing sentences are front-loaded and efficient, and the key constraint (no optimizer run) lands early. However, the middle block describing the three host modes for the 'Start the run' button is long, chatty, and largely about UI plumbing rather than helping an agent decide to call the tool or how to invoke it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must cover returns; it does by describing the card contents, the text-only fallback (region counts and estimate), and the error object. It omits whether the card is returned as part of the tool result payload versus rendered side-effect only, which is a minor gap for an interactive-render tool.

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

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

With schema description coverage at 0%, the description carries the burden and does so: it names yaml_path and clarifies that 'the problem YAML' is expected and that 'relative paths start at the work folder', which the bare string schema does not convey. It does not specify the file extension or an example path, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Show a problem YAML ... as a 3D view in the chat') and enumerates exactly what the view contains: design space, fixed/keep-out/solid/load regions, load-case arrows, and time/memory estimate. It explicitly distinguishes itself from check_problem ('the same checks as check_problem, in the same time') and from run_topopt ('No optimizer run').

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

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

'Use it when the YAML is ready, so that the user sees the setup before the run' gives a clear trigger condition. It also routes the agent to the sibling alternative for the full facts and warnings ('The full facts and the warnings are in check_problem'). No explicit when-not-to-use case is stated, keeping it below a 5.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true; the description is fully consistent with those traits and adds extensive operational detail. It discloses the job.stop file mechanism, exit code 5, absence of post step and result/, checkpoint/snapshot preservation, idempotent already_requested handling, stale-lock behavior, and the fact that a long or hung pass may delay or never observe the request.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the key behavior, then organized around run_dir, reply states, and special cases. It is necessarily long because the tool exposes many state-machine outcomes, but it is dense and some passages could be tightened. Still, most sentences carry operational information rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description documents reply states such as stop_requested, already_requested, postprocess, nothing_to_stop, gone, none, and several, plus note, found_by, pid, iteration, and options. Given the complex edge cases, the description provides enough context for an agent to call the tool and interpret results correctly.

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

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

Schema coverage for run_dir is 0%, so the description must compensate, and it does. It explains the default resolution logic, live-lock scanning, multiple-live-run behavior, fine-pass folder handling, and the restriction that only run folders with status.json or run.json count. This is substantially more than the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource: ask a running run to stop at the end of its current pass. It immediately distinguishes its behavior from alternatives by saying it returns at once, sends no signal, and waits for nothing. The purpose is unambiguous without needing the schema.

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

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

The description gives explicit usage conditions for default run discovery, multiple live runs, post-process states, already-completed runs, stale locks, and fine-pass interleaving. It tells the caller when to pass run_dir and what happens if several runs are live. It also names resume=true as the route for inspectable finished/post-process runs.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the important edge case: an unmatched or missing role returns the role list rather than an error, and it explicitly calls that 'a fact, not an error'. It also states the text is identical to the MCP prompt and the topopt://roles/<id> resource, which prevents an agent from double-fetching.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, and the alias/fallback details are valuable. The middle paragraph about clients running sub-agents is contextually interesting but marginal filler for an agent trying to call the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a single optional parameter and no output schema, everything an agent needs is present: what the tool returns, what a playbook contains, how aliases resolve, and what happens on a miss. Nothing material is left to inference.

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

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

Schema coverage is 0% and the only parameter, role, is fully explained: accepted values, case-insensitivity, agent-name aliases (cad-engineer), resource-URI form (topopt://roles/cad), and the null default behavior. This is exactly the compensation the low coverage requires.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it returns role playbooks for the five topopt team roles and enumerates them explicitly, so the resource is unambiguous. The verb is implicit ('Playbooks for...') rather than a direct 'get/return', but it is still far from tautological and is clearly distinguishable from every sibling tool listed.

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

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

It explains the role-vs-agent model and clarifies that one agent can play all five roles, which is real usage context. It also spells out the discovery path when no role is supplied. What it lacks is an explicit statement of when in a workflow an agent should call this versus jumping straight to other tools.

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

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

Goes well beyond the annotations: discloses background execution returning immediately, exit-code semantics (0/3 done-or-limit, 1 bad input/no solver, 2 missing gmsh/meshing failure/memory refusal), a structured error envelope with a facts field, memory refusal via max_gb and force override, and that estimate_only meshes nothing. This is exactly the mutation/concurrency/resource context annotations alone cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the estimate-only workflow, and each block maps to a parameter or result concern, so little is wasted. It is however dense and telegraphic in places ('With gate it replaces the YAML stress limits'), which costs a little readability for an otherwise well-organized text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter, no-output-schema, destructive-capable tool, the description supplies error shapes, result keys, exit codes, resource references (topopt://levers/verify_run) and caveats about p99.9 vs peak. No output schema exists, and the description compensates by naming the return keys the agent must read.

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

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

Schema coverage is 0% across 15 parameters, so the description carries the full burden — and it does, explaining estimate_only, allowable_mpa/percentile semantics and the limit block, run_dir defaults, gate vs YAML limits, max_gb/force interaction, mesh_size_mm defaults, levels_mm reference level, region_band_mm membership rule, solver auto-passing, yaml_path fallback, near_region_mm, load_sensitivity bands and part_only's boundary-condition effect.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (von Mises stress per load case on the final STL with quadratic tets) and explicitly distinguishes itself from the optimizer path ('independent of the voxel optimizer'). An agent can tell this apart from run_topopt and run_result without opening any schema.

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

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

Gives an explicit two-step workflow (call with estimate_only=true, report numbers, re-call with false), names verify_status as the follow-up for results, and states the exclusion 'one verify job or optimizer run at a time: a second start is refused'. Defaults for run_dir and prerequisites (run.json, result/final.stl) are also spelled out.

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

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

The annotations declare readOnlyHint=false, but the description frames the tool purely as a status/result viewer that shows state and returns verify.json content. That is an annotation contradiction: a read-only polling tool is described while annotations mark it not read-only. Although the description otherwise adds rich behavioral detail about states, coverage, and result matching, the contradiction forces a low score here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then organizes polling, state values, result semantics, and coverage details. It is long and somewhat dense, but most sentences earn their place because the tool has no output schema and needs to explain complex status/result behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still fully explains the returned state values, result content, result_matches_final_stl, partial/coverage fields, plain output, and log_tail behavior. An agent has enough information to poll correctly and interpret the response.

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

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_dir is explained as the run folder with its default, and result is explained as whether to include the result, including setting it false for state only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: show the state of a verify job and, when done, its result. It also distinguishes this from verify_run by explaining when a stale result means verify_run should be rerun.

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

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

It explicitly says to call the tool again to watch the job, names the terminal states that end polling, warns that no callback will occur, and directs the agent to run verify_run again when result_matches_final_stl is false. That gives clear when-to-use and alternative guidance.

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