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

Annotations already declare the safety profile (not read-only, not idempotent, not destructive, closed-world), so the bar is lower. The description adds one genuinely useful behavior beyond the schema: every point's files are persisted for scaps_results and scaps_plot. It does not warn about combinatorial cost for grid mode, partial failures in a batch, or long-run job behavior.

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 with the core action front-loaded and the file-retention note placed after. Nothing is padded, though the trailing sentence is a workflow hint rather than part of the core purpose and could be tightened.

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 11 parameters, nested objects, full schema coverage, annotations and an output schema, the description covers what the tool does and what it leaves behind. The remaining gap is operational expectations for a batch tool (cost of grid expansion, what happens to points that fail), which would matter for an agent planning a large sweep.

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 100%, so the baseline is 3; each of the 11 parameters, including the grid/zip mode distinction and the variables shape, is documented in the schema itself. The description adds no interpretation beyond that, such as how definition vs parameters vs variables interact.

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: run one SCAPS session over many parameter values and tabulate J-V metrics per point. It also enumerates the study types covered (thickness, doping, defect, band offset, temperature, intensity, bias). It never explicitly contrasts itself with the closest sibling, scaps_simulate (single run) or scaps_optimize, so sibling differentiation is left implicit.

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 usage through the list of covered sweep types and names downstream consumers (scaps_results, scaps_plot) via the retained per-point files, which is a useful workflow hint. However, there is no explicit 'use this instead of scaps_simulate when you have more than one value' routing statement and no 'when not to use' conditions.

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=false, destructive=true, idempotent=true, and openWorld=false, so the description does not need to carry the full safety burden. It adds useful context that the result is saved as a .def file and that layer material files are applied before explicit overrides, but it omits overwrite behavior and file-collision risk despite the destructive 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 two short sentences with the primary purpose front-loaded and the material-override rule efficiently appended. Every sentence adds useful information without waste.

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 rich schema, output schema, and annotations present, the description is largely sufficient for correct invocation. The main remaining gap is overwrite/destructive behavior, which is only flagged by annotations and not explained in the description.

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 high at 88%, so the schema already documents most parameters. The description adds meaningful semantics for the layers parameter by explaining that a named .material file is applied first and explicit keys override it, which is not fully captured in the schema example.

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: build a new device from scratch and save it as a .def file. The phrase 'from scratch' distinguishes this from edit_device and import_file, which are adjacent siblings in the toolset.

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 creation context is clear from 'build a new device from scratch,' which implies use when no existing device is being modified. However, it does not explicitly name edit_device or import_file as alternatives or state when not to use this tool.

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 this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond annotations: it specifies the file content categories returned, explains script-style field names and units, and notes that graded layers report their base value.

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 short and front-loaded: it first states the core read action and returned content, then adds the important field-name/unit behavior. It contains no 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?

Given the rich annotations, high schema coverage, single parameter, and existing output schema, the description provides enough context for correct selection and invocation. It explains what the tool reads and how fields are represented without redundantly documenting the output schema.

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 already has 100% schema description coverage, including an example definition filename. The description does not add further meaning about the `definition` input itself; its extra detail concerns returned fields and round-tripping values rather than the 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 description gives a specific verb and resource: it reads a `.def` file and enumerates the contents it exposes (layers, bulk defects, interfaces, contacts, realism checks). It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as `scaps_edit_device` or `scaps_create_device`.

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 read-oriented purpose implies when the tool is useful, and the note about passing values back as parameters hints at a workflow with editing/creation tools. However, there is no explicit when-to-use guidance, no exclusions, and no named alternative 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is largely covered. The description adds scope by listing parameters, layers, defects, materials, and solver settings, but it does not elaborate on overwrite behavior or structural operations beyond what the schema already documents.

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 single front-loaded sentence with no wasted words. It states the core action and output file format immediately.

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 rich schema coverage, an output schema, and destructive annotations, the description is largely sufficient for invoking the tool. Its main gap is that it does not help an agent choose between editing and sibling creation or scripting tools.

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 100%, so the schema carries the burden of parameter meaning. The description only lists broad edit categories and does not add syntax or mapping details beyond what 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 description states a clear verb and resource: change a device and save it as a .def file. It also names the editable areas, so an agent can distinguish it from pure read or simulation tools, though it does not explicitly contrast with create_device or run_script.

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 no explicit when-to-use or when-not-to-use guidance. It implies editing an existing base definition, but it does not name alternatives such as scaps_create_device or scaps_run_script.

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 genuine behavior beyond annotations: definitions and materials are parsed for validity and missing referenced files are reported back. However, annotations declare destructiveHint=true while the description only says 'Add', never disclosing that an existing file may be overwritten or what the overwrite flag destroys.

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 front-loaded sentences; the parenthetical example list earns its place by tying file types to the kind enum. Minor waste in the trailing newline and a slightly run-on second sentence, but no 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?

Output schema exists so return values need no explanation, and required inputs are covered by the schema. The gap is the destructive overwrite path and per-kind placement of files, which the description leaves entirely to annotations and the schema.

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 75%, and the description adds meaning beyond it by indicating that validation applies only to definitions and materials and that dependencies (absorption, grading, filter) can be missing. The undocumented 'overwrite' parameter is left unexplained in both places.

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 ('Add ... to the installation') and resource (a SCAPS file), and enumerates concrete examples (.def, .material, .abs, spectrum, measurement) that map onto the kind enum. It implicitly distinguishes itself from scaps_create_device/scaps_edit_device by framing the input as a file someone else shared, though it never names those 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?

'a SCAPS file someone shared' hints at the import-vs-create distinction, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many siblings (scaps_create_device, scaps_write_data). The agent must infer that this is for externally supplied files.

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=false, destructive=false, idempotent=false, and openWorld=false. The description adds that a finished job contains its full result and that cancel is possible, but it does not explain cancellation side effects, blocking behavior beyond wait_seconds, or permissions.

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 menu and a useful note about finished-job results. No text is wasted.

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 an output schema and annotations, the description needn't explain return values or safety. It still leaves gaps about job lifecycle, action-specific conditions, and how this differs from scaps_results/scaps_status, so it is adequate but not complete.

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 75%, with descriptions for action, job_id, and wait_seconds; the description loosely maps 'recent runs' to limit and 'one' to job_id, but does not add format or constraints beyond the schema. Baseline 3 is appropriate when the schema does most of the work.

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 specifies the resource (recent runs/jobs) and the operations (list, get/status, wait, cancel), so an agent can infer what the tool does. It does not name or distinguish sibling tools such as scaps_results or scaps_status, so it falls short of 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?

The action list implies the available modes, but there is no explicit when-to-use guidance, prerequisites, or alternatives such as when to use this versus scaps_results. The agent must infer usage from the enum and schema.

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 readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is fully covered. The description adds nothing beyond that: no pagination behavior, no indication of whether listing is recursive or shallow, no note on ordering. A 3 is appropriate given annotations carry the burden.

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?

One front-loaded sentence that names the resource first. The trailing 'and more' is vague and adds little, but overall there is no wasted 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?

Safety and return shape are handled by annotations and the output schema, so the essentials are present. However, for a paginated listing tool the description should at least acknowledge limit/offset behavior and the scope of what 'folder' means; those gaps leave the agent relying on the schema alone.

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 only 50%: kind and contains are documented, but limit and offset have no descriptions. The description's folder list merely restates the kind enum and does not explain pagination semantics or how contains interacts with listing, so it fails to compensate for the coverage gap.

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 (List) and resource (files in a SCAPS data folder), then names the folder categories covered. It is distinguishable from write/run siblings like scaps_write_data and scaps_run_script, though it does not explicitly contrast with read-ish siblings such as scaps_results or scaps_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 never says when to use this tool versus scaps_results, scaps_status, or scaps_describe_device, nor any prerequisites. Only the folder enum loosely implies usage; there is no explicit when/when-not 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?

Adds meaningful behavior beyond annotations: bounded Nelder-Mead, one SCAPS session per measurement condition per simplex step, multi-measurement support, and job continuation after wait_seconds. With annotations already declaring non-read-only/non-idempotent status, this is rich process context, though side effects on files are not fully spelled out.

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 and compact: it states the core action first, then measurement support, then job behavior. Every sentence contributes, though the GUI-fitter replacement context is somewhat secondary.

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 complex 12-parameter schema, existing output schema, and 92% schema coverage, the description supplies the needed process context: fitting vs optimisation, multiple measurements, and long-run job polling. It is complete enough for invocation, with only minor gaps around side effects and sibling alternatives.

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 92%, so the schema already documents parameters such as goal, measured curves, variables, and actions. The description adds conceptual context for fitting/optimisation but little parameter-level detail beyond what 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?

States specific actions (fit measured curves, optimise efficiency/Voc/Jsc/FF) on SCAPS device parameters and names the method (bounded Nelder-Mead). It is clear what the tool does, but it does not explicitly contrast itself with simulation siblings such as scaps_simulate or scaps_batch.

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 clear usage context for fitting versus metric optimisation, and explicitly says long runs past wait_seconds should be polled with scaps_jobs. It does not provide explicit when-not-to-use guidance or contrast with scaps_simulate/scaps_batch.

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 this as a safe, idempotent, non-destructive read. The description adds one genuinely useful piece of context the annotations cannot convey: it requires the optional 'plot' extra, which can fail if uninstalled. However, it says nothing about how the PNG is returned (inline content, file path, base64) or how overlays are composed, which matters for a 9-parameter render tool.

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, no filler, with the action front-loaded. Brevity is appropriate; the issue is missing content rather than excess.

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 9-parameter tool with no output schema, an undocumented return shape and half the parameters undescribed, the description is too thin. An agent cannot tell what it receives back or how to control axis scaling and image size from the description alone.

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 only 56%, and the description contributes zero parameter information. Key controls like log_x, log_y, and width_px have no description anywhere, and the overlay semantics of the 'files' array are only partially covered by 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?

States a specific verb and output artifact: render result curves as a PNG image. This differentiates it implicitly from data-oriented siblings like scaps_results, but it never names that sibling, so the differentiation is left to inference.

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?

There is no explicit guidance on when to call this versus scaps_results (fetch data) or scaps_optimize. The only usage-adjacent statement is the dependency on the optional 'plot' extra, which is a prerequisite, not a when-to-use rule.

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, and closed-world behavior, so the safety profile is covered. The description adds that only one table is returned at a time and what table categories exist, but says nothing about pagination/truncation from max_rows/offset, file-listing behavior, or error handling.

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?

A single front-loaded sentence with zero filler. The table-type enumeration is compact and directly useful, and 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?

The tool has an output schema and annotations, reducing what the description must cover, and it explains the one-table-per-call model and table types. However, it omits important retrieval behavior: the default max_rows cap of 200, offset/thinning semantics for long profiles, and the file-listing fallback when 'file' is omitted.

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 71% schema coverage, the baseline would be 3, but the description meaningfully supplements the 'table' parameter by enumerating valid table categories (J-V, QE, C-V, C-f, band, generation, AC profiles) that the schema does not constrain via enum. It does not clarify offset/max_rows/step paging semantics, which lack descriptions in 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?

States a specific verb and resource ('Return one table of a result file') and enumerates the table types (J-V, QE, C-V, etc.), making the tool's function clear. It does not explicitly differentiate from siblings like scaps_list_files or scaps_plot, but the core purpose is 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?

The description implies usage for extracting a single table, and the schema notes that omitting 'file' lists files, but there is no explicit when-to-use guidance or named alternative (e.g., scaps_list_files for listing, scaps_plot for visualization). Implied usage only.

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, which only flag destructiveHint=true. It discloses implicit script mutation (server prepends 'quit', error-log settings, and 'clear all'), a validation gate against the installed SCAPS version, sandboxing rules (bare file names, system commands rejected), and the mechanism by which outputs are collected ('save results.<kind> name'). That explains both why the call is destructive and how to retrieve artifacts.

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 clause, then a compact block of execution constraints follows with no filler sentences. Slightly dense as a run-on of constraints, but every clause carries information an agent needs.

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 an output schema present, return values needn't be explained, and the annotations carry the safety profile. The description covers prepended commands, validation, sandbox rules, and result collection; the only gaps are the long-run job handoff and timeout semantics, which are covered by the schema.

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 100%, so script, timeout_s, wait_seconds, and validate_only are already documented in the schema. The description adds nothing parameter-specific — neither the wait/job-continuation tradeoff nor validate_only is referenced in prose. The 'save results.<kind> name' note describes script content, not an input 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?

States a specific verb and resource ('Run a SCAPS script') and immediately scopes it against the sibling family with 'for workflows beyond the other tools', then enumerates the escape-hatch use cases (recorder, curve fitting, math, loops, tandem). An agent can distinguish this from scaps_simulate, scaps_batch, or scaps_optimize 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?

'For workflows beyond the other tools' clearly signals this is the fallback/general-purpose tool rather than a first choice, and the enumerated use cases make the intended context concrete. It stops short of naming which specific sibling to prefer for common cases (e.g. 'use scaps_simulate for a single IV curve'), so the exclusions remain implicit.

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, and non-destructive behavior, so the description need not restate safety. It adds that the reference is tied to the installed SCAPS version and explains notation placeholders in command entries, though it does not describe matching behavior or result scope beyond that.

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 one sentence, and the notation legend is compact and relevant. The legend could be more tightly tied to 'returned command list', but there is little waste.

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?

An output schema exists and annotations cover safety, so return format and side effects need not be explained. Still, an agent lacks explicit routing guidance and any explanation of query matching or limit behavior; adequate but with visible gaps.

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 documents the required query parameter with examples, and the description adds domain vocabulary for numbered forms and <none> placeholders, which helps interpret/search command tokens. However, it never mentions the limit parameter or query matching semantics, so it only partially compensates for 50% schema description coverage.

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 ('Search') and resource ('command list of the installed SCAPS version'), making it clearly a reference lookup rather than script execution or simulation. Sibling tools such as scaps_run_script and scaps_simulate are distinct from this.

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 implied use is to look up command syntax for the installed SCAPS version, but the description gives no explicit when-to-use/when-not guidance or alternatives. It does not say to consult this before scaps_run_script or clarify that it only searches rather than executes.

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 non-read-only, non-destructive, non-idempotent, closed-world behavior, so the bar is lower. The description adds genuinely new behavioral facts: overrides are run-scoped and not persisted, and artifacts remain reachable through scaps_results and scaps_plot. It does not describe job continuation semantics or cost/failure behavior, but that is largely covered by the wait_seconds schema field.

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?

Three short sentences, front-loaded with the verb and outputs, then analysis, then persistence semantics. No filler; the only slightly soft phrase is 'realism checks', which is never unpacked.

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?

Output schema exists so return values need not be explained, and the description covers analysis results, override scoping, and artifact access. For a 12-parameter simulation entry point it is nearly complete; the main gaps are sibling routing and the meaning of 'realism checks'.

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 100%, so the schema already documents all 12 parameters in detail. The description adds no parameter-level meaning (e.g. how 'parameters' interacts with 'definition', or what 'profiles' require). Baseline 3 is appropriate.

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 ('Simulate a device') and enumerates the computed outputs (J-V, QE, C-V, C-f, spatial profiles) plus analysis. It does not explicitly separate itself from close siblings like scaps_run_script or scaps_batch, though the mention of scaps_results/scaps_plot hints at its position in the workflow.

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?

Usage is implied by the scope ('Overrides apply to this run only') and by pointing to scaps_results and scaps_plot for persisted output, which routes the agent after a run. There is no explicit when-to-use / when-not guidance relative to scaps_run_script, scaps_batch, or scaps_optimize.

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 readOnlyHint, idempotentHint, and closed-world behavior, so the safety profile is covered. The description adds that this is a detailed-balance calculation (not a device simulation), but says nothing about cost for up to 200 band gaps, whether one result per gap is returned, or temperature's effect on the limits.

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?

One compact sentence with the output quantities front-loaded and the input framing second. It wastes no words, though the phrase 'under a SCAPS spectrum' is slightly opaque compared to the schema's clearer AM1.5G default.

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?

An output schema exists, so return-value detail is not required, and the description names the computed quantities. However, for a tool that runs a SCAPS-based calculation alongside job/queue siblings, it omits whether the call is synchronous, how long many band gaps take, and how temperature factors in.

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 67%: spectrum and band_gaps_ev are documented in the schema, and the description only mirrors those concepts ('given band gaps', 'SCAPS spectrum'). The undocumented temperature_k parameter is not clarified by the description either, so this sits at the baseline for partial coverage.

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 (compute detailed-balance limits) and resource (Jsc, Voc, FF, efficiency for given band gaps), which is far more precise than the bare title. An agent can distinguish it from simulation siblings like scaps_simulate or scaps_optimize, though no sibling is named 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?

The implicit use case (theoretical limiting efficiency for one or more band gaps) is inferable from the wording, but there is no explicit when-to-use, no mention of when to prefer scaps_simulate, and no prerequisites such as requiring a SCAPS spectrum file to exist.

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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying that it reports the installation in use, how it was discovered, other installations, the run folder, and jobs, which tells the agent what diagnostic information 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 definition is a single front-loaded sentence with no filler. The list of reported items is slightly run-on and the phrase 'how it was found' could be tightened, but it remains appropriately sized for a status 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 an output schema present, rich read-only annotations, and zero parameters, the description is nearly complete for the tool's complexity. It identifies the report contents but does not clarify the discovery-method concept or the relationship to scaps_jobs, leaving a minor contextual gap.

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 there are no parameter semantics to explain. With no inputs, the baseline is 4; the description appropriately does not waste space on nonexistent parameters.

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 (Report) and resource (SCAPS installation status), and enumerates what is included: installation in use, discovery method, other installations, run folder, and jobs. It clearly distinguishes itself as the diagnostic/status tool among the scaps_* siblings, though the phrasing 'how it was found' is slightly ambiguous.

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 a diagnostic/status use case but gives no explicit guidance on when to call this versus alternatives such as scaps_jobs or scaps_results, even though it mentions jobs. The intended usage is inferable from the title and report contents, but not 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?

Annotations declare destructiveHint=true for a file-writing tool, yet the description never mentions that an existing file may be overwritten or that overwrite defaults to false and must be set deliberately. It also says nothing about where files land or whether writes are visible to other tools. Beyond restating 'right format and units', it adds no behavioral context that the annotations do not already carry.

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 with the core action front-loaded and the supported data types listed after. There is minor waste in the vague phrase 'with the right format and units', which conveys little the schema doesn't.

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?

The output schema and rich parameter schema relieve the description of return-value and per-parameter explanation. However, for a 19-parameter destructive write tool, the description is thin on the overwrite/safety story and on how kind selects which optional parameters matter.

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 95%, including per-kind semantics for x, y, quantity, and x_unit, so the schema does most of the work. The description adds only the general 'format and units' framing, with no extra cross-parameter guidance (e.g., matching quantity to kind or units to x_unit). Baseline 3 is appropriate.

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: write numeric data as a SCAPS input file, including that formatting and units are handled. It enumerates the data families (absorption, spectra, generation, filters, grading, measurement), which maps cleanly onto the kind enum. It does not distinguish itself from scaps_import_file, which could plausibly handle similar data.

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 second sentence gives a positive usage scope that matches the six kind values, so an agent can tell roughly when the tool applies. There is no guidance on when not to use it, no mention of scaps_import_file as the alternative for existing files, and no note on when overwrite should be set.

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