MIDAS CIVIL NX tools (MIDAS IT Europe)

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

The description adds substantial behavioral context beyond annotations: it explains naming rules (prefix + cleaned section/material names, 40-character cut, UNASSIGNED fallback), ordering (largest group first), overwrite semantics ('members are ADDED... it never removes members'), and write verification (re-reads db/GRUP, batches, read-back checks). These details are critical for a mutating tool and are not contradicted by 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 front-loaded with purpose and scope, then layers in optional behaviors and safety details. It is dense but mostly earns its length; minor readability could be improved by breaking the single long paragraph into shorter logical chunks.

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 the description must carry the burden of explaining results. It mentions the preview/planHash workflow and the undo tool, but it does not detail the preview response structure (e.g., proposed group names, counts, planHash). For a complex 8-parameter mutating tool, this is a small remaining 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?

Schema coverage is 100%, so the baseline is 3. The description earns a 4 by adding meaningful behavior for key parameters: how 'existing: overwrite' merges rather than replaces, how 'groups' limits the write to named preview groups, and how prefix/minElements/includeNodes affect the generated groups.

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 opens with a precise verb and resource: 'Creates one structure group per section, per material, or per section + material pair.' It clearly scopes the tool to grouping by section/material using the Auto Structure Groups engine, making it easy to distinguish from sibling operations like auto_structure_groups_undo.

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 explains the preview-first workflow ('Previews unless apply: true with confirmPlanHash') and names the undo sibling as the reversal path. It does not explicitly compare to other grouping or stage tools, but the workflow guidance is clear enough to select and invoke the tool correctly.

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 annotations already declaring destructiveHint=true, the description adds substantial behavioral detail: it deletes created groups, restores prior membership from a pre-write snapshot, and refuses to delete groups currently used by construction stages because deletion strips them from stages. This explains exactly what destruction and restoration occur.

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 four tight sentences, front-loads the core undo behavior, then adds the refusal condition, default resolution, and preview/apply semantics. Every sentence carries useful 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?

For a destructive ledger-based undo tool with annotations and a simple schema, the description covers what is undone, what is restored, why the operation may be refused, which run is targeted by default, and how preview mode works. No output schema is present, so no return-value explanation is needed.

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%, and the apply parameter has no schema description. The description compensates by explaining that apply defaults to false and previews unless apply is true, while also clarifying the runId default as the latest not-yet-undone run.

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 reverses an auto_structure_groups run from the ledger. It clearly distinguishes the undo operation from the forward auto_structure_groups tool by naming what gets deleted and restored.

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 usage context: default targets the latest run not yet undone, previews unless apply is true, and refuses while a construction stage uses one of the affected groups. It does not explicitly name alternatives such as auto_structure_groups or stages_undo, so it falls short of the highest bar.

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 far beyond the annotations: discloses that preview writes nothing, that a write re-reads the model and refuses if the planHash changed, the exact write order, rollback on partial failure, the destructive deleteSourceBeams behaviour (with undo path), and that it runs as a background job requiring job_status polling. This is exactly the extra context annotations can't 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?

Front-loaded with the core action, but the body is a dense run-on paragraph listing many behaviours with little structural separation, making it harder to scan than it needs to be. The content largely earns its place, but the presentation hurts 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 35-parameter, destructive, job-based tool with no output schema, the description covers the write lifecycle, safety, rollback, background-job polling, and the contents of the preview. Return-value detail is partially covered via the preview contents; a little more on the write result shape would complete 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 100%, so the baseline is 3; the description still adds value by tying apply and confirmPlanHash together (write refused if plan differs) and flagging deleteSourceBeams as destructive and skipped for slices. It doesn't explain every parameter, but the schema already does that 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?

States a specific verb, resource, and engine ('Converts beam elements into a plate (or solid) mesh of their cross-section with the Beam to Plate plugin's own engine'), enumerates the section types handled, and is clearly distinct from b2p_survey (survey) and b2p_undo (undo). An agent can identify exactly what this tool does without opening 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?

Explicitly states the workflow: previews by default and writes nothing, write only with apply + confirmPlanHash, 'Use b2p_survey first', and the run is recorded for b2p_undo. The sequencing is clear, though it never states when NOT to use it or names a competing alternative beyond the prerequisite 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 read-only and closed-world; the description adds real behavioral context beyond that — the plugin-version fidelity criterion, the comparison source (/ope/SECTPROP), the enumerated verdicts with reasons, and the background-job/polling mode on the website. Pagination and response shape are not described, and no output schema exists, which keeps it off a 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?

The purpose is front-loaded, but the opening sentence is an extremely long comma-chained enumeration of every output field, and the selector constraint only appears after it. The content earns its place, but the structure makes 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 15 parameters, nested objects and no output schema, the description does the work of explaining what the tool returns (verdicts, reasons, suggestions, material slots, units, element estimate). Selector exclusivity and the background-job behavior are covered. Only pagination/response envelope details are left unspecified.

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 baseline is 3, and the description earns a point above it by stating a constraint the schema does not: the four beam selectors are mutually exclusive, use ONE of them, with 'every beam' as the default. That is genuine meaning added over the structured fields.

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 reads the model as the Beam to Plate plugin (1.0.6) does and surveys each section against CIVIL NX's published /ope/SECTPROP properties to produce a convert/blocked verdict. This is clearly a diagnostic pass, distinguishable from the mutating sibling b2p_convert, and no schema needs opening to know what it produces.

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 tells the agent how to scope the run ('Choose beams with ONE of elementIds, sections, groups or useCivilSelection (default: every beam)') and warns that acceptSections must only be used with the user's agreement. It also notes the website deployment runs as a background job to be polled with job_status. It stops short of explicitly saying 'run this before b2p_convert', which is the natural next step an agent would need.

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 flag destructiveHint=true, and the description goes well beyond them: it lists the exact categories of model entities removed, which are restored to the original beams, that it re-reads the model afterwards, and that tidy additionally deletes thickness records and the 'B2P mesh' group that the plugin's own Undo leaves behind. Resumability and the dry-run default are behaviors 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?

All content is relevant, but it is delivered as one very long run-on paragraph where resumability, tidy behavior, default run selection and preview/apply mode are interleaved. Front-loading the undo purpose is good, but the behavioral clauses would scan far better as separate sentences or bullets.

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 covers what an agent needs: default target selection, preview-versus-apply, what a partial failure returns ('says what is left'), and how to resume. Nothing material about invoking this tool safely 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?

With 67% schema coverage, the description compensates for the undocumented `apply` parameter (previews unless true; runs as a background job on the website) and reinforces `runId`'s default. `tidy` is already fully documented in the schema, so the description adds little there, keeping this just under 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 ('Undoes') and a specific resource (a b2p_convert run from the ledger), and enumerates exactly what is reverted versus restored. An agent can distinguish this from b2p_convert or the other *_undo siblings without opening 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?

Explicit call conditions: default targets the latest not-undone run, it previews unless apply:true, and repeated calls with the same runId resume after a partial failure or a stopped background job. The only minor omission is naming b2p_convert directly as the paired tool, but the runId semantics make that obvious.

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 set, the description adds crucial context: previews write nothing, apply requires a matching planHash, the model is re-read and refused if changed, written elements are read back, and the run is recorded for bridge_reshape_undo. It also notes the background job and job_status polling.

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 every clause is informative, but it is a dense, long block with many semicolon-separated details. For a 15-parameter mutation tool the length is justified, though bullets or shorter sentences would improve scanability.

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 destructive mutation tool with no output schema, the description covers the essential workflow: read first, preview default, confirm before writing, stale-plan refusal, undo recording, units, and background execution. An agent has enough to invoke it safely.

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 already 93%, so the baseline is 3. The description adds meaningful consequences beyond the schema for key parameters, such as 'parallel' moving nodes only versus 'square' re-meshing the deck, 'follow' vs 'rigid' substructure behavior, and the apply/confirmPlanHash workflow.

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 opens with a specific verb and resource: 'Changes the geometry of the bridge in the open model in place.' It enumerates the four main capabilities (spans, skews, alignment, levels) and distinguishes itself from bridge_reshape_read and bridge_reshape_undo.

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 'Use bridge_reshape_read first' and describes the two operating modes: preview by default versus 'With apply: true and confirmPlanHash'. It also states when 'square' cross members are valid and when they are not ('not with new levels').

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 state readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it says the read reports which axis it used, reports the girders' extent and supports found, can return a plan drawing, and on the website runs as a background job to poll with job_status. It does not describe failure modes or authorization needs, but the added async and reporting behavior is substantive.

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 read action and is mostly made of relevant clauses about what is read and how to invoke it. It is dense and somewhat run-on in the first sentence, but the length is justified by the complexity of the bridge-reading operation.

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 read operation, optional parameters, read-only annotations, and no output schema, the description is largely complete: it explains what model elements are read, that a plan drawing can be returned, that the read reports its chosen axis and found supports, and that it should precede bridge_reshape. It stops short of documenting the exact return structure or failure behavior, which keeps it from a 5.

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 input schema already documents axis, picture, supports, and deckGroups in detail. The description adds little parameter-specific meaning beyond mentioning the plan drawing and that the read reports the supports it found; baseline 3 is appropriate when the schema carries parameter semantics.

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 the open bridge model as the Bridge Reshaper plugin does. It then enumerates exactly what is read, including deck, spans, supports, skews, girder/edge lines, bearings, substructure, direction, levels, and plan drawing, which clearly distinguishes it from siblings such as bridge_reshape.

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 'Use it before bridge_reshape' and notes that on the website it runs as a background job requiring job_status polling. It gives clear context for when to use the tool, though it does not name when-not-to-use cases or alternative read 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 flag destructiveHint=true and readOnlyHint=false, yet the description goes far beyond them: it names exactly what is restored and removed, the refusal conditions (different model, model edited since apply), that force overwrites those edits, resumability semantics, and that the website apply runs as a background job. This is the kind of context annotations cannot express.

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-loads the core action and effect, then layers refusal conditions, resumability, default run, and preview/background behavior. Dense but nearly every sentence carries distinct information; the resumability and background-job clauses could be trimmed slightly without loss of safety-critical meaning.

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 destructive, resumable mutation tool with no output schema, the description covers outcome (model returns exactly), failure reporting, retry behavior, and dry-run default. An agent has everything needed to decide whether and how to call it, including the destructive override path.

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% and leaves apply undocumented, but the description compensates fully: 'Previews unless apply: true' explains apply, force:true is described as undoing anyway while overwriting edits, and runId's default (latest not-yet-undone run) is spelled out. Each parameter's behavioral effect is clear, not just its name.

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 (undoes) and resource (a bridge_reshape ledger run), and describes the exact effect: rows overwritten are written back, rows created are removed. It is clearly distinguishable from bridge_reshape (which applies) and bridge_reshape_read (which reads) without inspecting 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 concrete when-to-use context: default targets the latest not-undone run, apply:true is needed to execute, force:true overrides the 'model edited since apply' exclusion, and re-calling retries only failed steps. It does not explicitly name bridge_reshape_read or bridge_reshape as the alternative to pick for non-undo needs, but the exclusions and prerequisites are unusually complete.

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=true and openWorldHint=false, but the description goes further by describing the HTTP shape (GET /db/<TABLE>) and the return contract: rows keyed by id, either the requested ids or the first `limit` rows. That return-shape disclosure is real added value; only error/unknown-table behavior is missing.

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 verb/endpoint, then the return contract. The example-key list is moderately long but serves as useful grounding for the required `table` parameter, so it earns its place.

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 what comes back, and it does (rows keyed by id, ids-vs-limit selection). For a simple 3-parameter read tool with read-only annotations, this is nearly complete; only unknown-table or empty-result behavior is unaddressed.

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%; `ids` and `table` are already documented in-schema, including 'Omit for the first `limit` rows.' The description restates that interplay rather than extending it, and says nothing about `limit`'s default of 50 or its 500 cap, which the schema also leaves undescribed.

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 ('Reads one MIDAS database table (GET /db/<TABLE>)') and lists concrete table keys (NODE, ELEM, LOAD types), so an agent knows exactly what is fetched. It does not explicitly contrast with nearby siblings like result_table_catalog or preview_result_table, 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 table-key examples imply when the tool applies, and 'Read-only' signals safe usage, but there is no explicit guidance on when to pick this over result_table_catalog or preview_result_table, nor on the trade-off between fetching by ids versus scanning with `limit`. 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so "Read-only" is confirmatory rather than additive. What the description does add is the MAPI connection probe — signalling an external application dependency and possible connection failure — plus a preview of the returned inventory including per-key run history. It never says what happens when no model is open or the connection fails, so it is not fully transparent.

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 action and scope are front-loaded in the first clause, and the closing "Call this first" directive is well placed. The middle inventory is a long comma-separated run-on inside one sentence, which is dense but every listed item corresponds to a distinct returned data category.

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 and no parameters, the description carries the full burden of describing return content and does so with a concrete inventory; the connection-health signal is also covered. Missing is any statement about failure/degraded behaviour when CIVIL NX is unavailable or no model is open, which is the one gap an agent would benefit from before calling.

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 is nothing for the description to disambiguate; baseline is 4. Mentioning that recent runs are recorded "for this key" hints at implicit keying, but no argument semantics need explaining.

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 pair (checks connection, summarises model) and enumerates exactly what is reported — units, moving load code, row counts, group names, static load cases, stages, combinations, recent runs. That enumeration clearly separates it from nearby siblings such as model_bridge_summary or civil_read_table, so an agent can identify it without opening 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?

"Call this first" gives explicit ordering guidance relative to the other CIVIL NX tools, which is the main usage decision for a status tool. It does not name a competing sibling or state exclusions (e.g. when to prefer model_bridge_summary), 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 only say readOnly/openWorld; the description adds substantial behaviour: recursive envelope resolution to a deterministic single state, gating against MIDAS' own reported value, refusing rather than approximating, near-tie reporting, per-unit-length plate results, and that it executes asynchronously as a website job. These are real constraints an agent needs and none are in the structured fields.

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 in the first sentence and zero filler sentences. The middle sentences are extremely dense with nested parentheticals, which slows parsing, but nearly all content is substantive rather than 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?

For an 11-parameter, nested-object tool with no output schema, the description covers semantics, workflow dependency, units and inline row limits well. The gap is that it says 'Runs as a job on the website' without explaining how to check or fetch the job result (e.g. job_status), which an agent must know to actually obtain output.

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 already 91%, yet the description still adds value: concrete set-syntax examples with ranges ('15to20', 'N12', 'EL12'), the note that a range keeps only existing ids, 'keyItem must be in the set', default units and the per-unit-length plate convention. It goes beyond the schema without re-documenting 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?

States a precise verb+resource+scope: find the load state making one key effect extreme at one key item, then report all items' results in that same state. It explicitly contrasts this with 'each item's own envelope', so an agent can distinguish it from envelope-style result tools. 'Step 2' and the reference to concurrent_forces_setup also position it 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?

Gives a clear precondition ('Call concurrent_forces_setup first for names and keyEffect ids') and use case ('the coexistent forces a bearing, pier cap or connection check needs'). It does not mention the sibling concurrent_forces_probe or say when to prefer it, so alternatives beyond setup are left 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 readOnlyHint=true and openWorldHint=false, and "Read-only" merely repeats that. The description does add that it interrogates the CIVIL NX build per result-source kind rather than reading model data, which is useful context, but it says nothing about output size, cost of probing all seven sources, or what happens if the build doesn't answer.

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 a short identifier sentence, but the core sentence is a long run-on with a seven-item parenthetical and four coordinated clauses. Every element is informative, yet the density makes 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?

There is no output schema, and the description does describe the shape of the answer: table token, returned columns and their mapping, output-point tokens, and published result series. Combined with the trigger condition this is nearly complete; only failure/empty-result behavior is unaddressed.

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 100% and the nested units object with its force/length enums and "MIDAS converts / Default: the model's own" note is fully documented in the schema. The description does not mention units at all, so it adds nothing on top of the schema; baseline 3 applies.

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 (probe/ask the build) and a specific resource (table tokens, columns, output-point tokens and result series per result source), enumerating the seven sources it covers. It is clearly distinct from concurrent_forces (the reporter) but doesn't distinguish itself from adjacent siblings like result_table_catalog or preview_result_table.

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 concurrent_forces reports a missing table, column or series" gives an explicit trigger condition, which is exactly the context an agent needs. However, it names no alternative tool for the adjacent cases (e.g. catalog lookups when nothing is broken).

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=true and openWorldHint=false, and the description usefully adds domain behaviour: which case types (moving load, settlement, response spectrum, ABS/SRSS anywhere down the combination tree) cannot yield a coexistent state, that the reason and workaround are reported, and that unit conversion is applied. It does not cover cost, size of the payload, or error conditions.

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 scope is front-loaded ('Concurrent Force Reporter, step 1') and there is little filler, but the core is one enormous run-on sentence with semicolon-stuffed enumerations that is hard to parse. The breadth justifies length, yet the structure could be a short bulleted inventory.

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 carry the return shape entirely, and it does: the ten LCOM tables, MIDAS addressing, envelope flags, availability reasons, per-result-source items, keyEffect ids with units, groups, stage tokens, criteria/output positions and published status. An agent knows what it will receive before calling.

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 limit, units, search and includeConstituents. The description restates search and includeConstituents almost verbatim and says nothing about limit caps or the unit-conversion default, so it adds little beyond the schema. Baseline 3 applies.

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: reads the open CIVIL NX model and enumerates everything a concurrent-forces run can consume (load cases, result sources, key effects, groups, stages, units). The 'step 1' framing and 'Read-only' make it separable from concurrent_forces / concurrent_forces_probe, 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?

Usage context is implied by 'step 1' of a concurrent-forces workflow, and it gives per-parameter advice ('use search to narrow a long case list', 'includeConstituents shows each combination's children'). But there is no explicit statement of when to call this versus concurrent_forces_probe or concurrent_forces, nor any prerequisite/exclusion 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 flag destructiveHint=true and readOnly=false, but the description adds substantial behaviour the agent could not infer: composite sections and load combinations are preserved and restored, groups are validated first, a snapshot is kept for stages_undo, and the write is refused if the plan hash differs. That is exactly the extra context a destructive tool 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?

One dense paragraph that front-loads what is built and how it is written, with mode and preview/apply behaviour near the end. It is information-rich rather than padded, though the long parenthetical about composite sections makes the first sentence heavy and slightly harder 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 14-parameter tool with nested objects and no output schema, the description covers structure ordering, temporary groups, final stage, modes, validation, preview and undo. Remaining gaps are minor: it never says what the preview returns (notably the planHash needed for confirmPlanHash) and saveResult is left entirely to 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 79%, so the baseline is 3, but the description goes further by explaining sequencing semantics: groupsPerStage at a time, boundary/load groups riding in the first new stage, temporary groups toggled on and off with their stage, and an optional closing final stage. It does not explain saveResult or how naming/start interacts in replace mode, leaving some gaps.

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 names a specific verb and resource ('Builds a construction stage sequence') and identifies the exact machinery used (the Construction Stage Wizard plugin's bulk generator plus its stage planner). It also implicitly distinguishes itself from siblings such as stage_groups and cs_stage_summary by scoping the tool to sequence creation and write.

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 operating conditions: mode 'append' vs 'replace', preview-by-default unless apply: true, and validation before any write. What it lacks is an explicit pointer for when to choose a sibling instead, e.g. when to reach for stage_groups or cs_stage_report rather than this generator.

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 destructiveHint/idempotentHint annotations: it states that overwrite MOVES existing nodes and the elements on them, that new nodes are POST create-only so a node added after the preview is never clobbered, that overwrites use PUT, and that db/NODE is read back. It also enumerates the validation rules (duplicate ids, ids above 999999, coincident tolerance) that cause a write to be blocked.

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?

Almost every clause carries information and the verb is front-loaded, but it is a single dense paragraph with heavy parentheticals, so the agent must parse one long run-on rather than scan distinct sections. Nothing is wasted, though the structure could be broken up.

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 13-parameter, destructive, open-world-false tool with no output schema, this covers validation, numbering, overwrite consequences, unit handling and the preview/confirm flow. It stops short of saying what the call returns (created ids, planHash, the readback payload) and never routes against alternative node-creation siblings.

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 92% schema coverage the baseline is 3, and this description adds genuine semantics: what 'auto', 'start' and 'column' numbering each do and which is default, that an existing id blocks the write unless overwrite is set, that coordinates are converted from inputUnit to the model unit with an origin offset, and how the table blob (headers, decimal commas, semicolon CSVs) is parsed.

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+resource ('Creates nodes in the open CIVIL NX model') and immediately scopes it to the Node Generator plugin's own engine, including accepted inputs (nodes array or pasted table). It also names the paired sibling create_nodes_undo, so an agent can tell which side of the pair to call.

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 preview-then-write contract ('Previews unless apply: true with confirmPlanHash'), about overwrite requiring the user's agreement, and about the coincident report/skip/create decision. What is missing is routing versus other node-creating paths in the sibling list (e.g. dxf_import), which is never mentioned.

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 flag destructiveHint=true and readOnlyHint=false, and the description adds critical behavior beyond that: refusal conditions tied to dependent elements, the default run selection, and preview-vs-apply semantics. This is exactly the extra context an agent needs for a destructive operation.

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?

Four dense sentences, each carrying distinct information: what it reverses, the refusal precondition, the default target, and preview semantics. Front-loaded with the core action and 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?

No output schema exists, but the description covers the destructive effects, safety preconditions, default targeting, and preview behavior — everything needed to invoke a destructive undo 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 50% (only runId documented), but the description compensates: it explains that apply:true commits versus default preview, and that runId defaults to the latest un-undone create_nodes run. Both parameters gain meaning beyond the raw 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 ('Reverses') and resource ('a create_nodes run from the ledger'), then details the exact effects: deletes created nodes and restores overwritten nodes to earlier coordinates. This clearly distinguishes it from the sibling create_nodes 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?

Explicitly states a precondition ('Refuses while elements, structure groups or supports use the nodes it created (undo those first)') and clarifies the default target ('the latest create_nodes run not yet undone'). It doesn't name specific sibling undo tools, but the when/when-not conditions 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: it runs on the Wizard's own layout engine, needs no model, and returns the case groups each loading model requires. It does not discuss units, failure modes, or determinism, so it stops short of a 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?

Two sentences, front-loaded with the operation and then the use case. It is dense with standards jargon but each clause carries information, and there is no filler or repetition.

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 read-only, no-required-parameter tool with no output schema, the description covers the computation basis, the output content (case groups), and the intended usage. An agent has enough to invoke it correctly; only minor details such as return shape specifics are absent, which the absent output schema leaves implicit.

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 both the lanes object (with enumerated options such as M1S, M1C, M2, SV, HB, FW, ACC) and the section object (width, kerbOffset, markedLanes, footways, etc.) are already documented. The description mentions the loading models and cross-section context but adds no syntax or format detail beyond the schema, so 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 gives a specific verb ('Lays out') and a precise resource (CS 454 notional lanes, remaining areas, footways and strips on a carriageway cross-section), plus the exact layout engine and standard clauses it follows (Table 5.9a, cl 5.10). It also explicitly distinguishes itself from the sibling cs454_moving_loads, so an agent can tell the two apart 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?

It names the concrete use cases ('answer layout questions or to choose inputs before cs454_moving_loads') and states the key precondition ('Needs no model'), which routes the agent to this tool rather than the full moving-loads sibling. That is explicit when-to-use guidance with a named alternative.

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 explicitly says codeChange can 'DELETE every lane in the model', which is a destructive behavior, while annotations declare destructiveHint: false. This is a direct annotation contradiction, so behavioral transparency must be scored 1 under the rules despite otherwise rich behavioral detail.

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 dense but appropriately sized for a 15-parameter wizard and front-loads the core workflow before preview/apply details. The first sentence is quite packed, but no sentence is obviously 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?

For a complex tool with no output schema, the description explains the main preview output fields, the apply behavior, deck-reading fallbacks, undo recording, and overwrite safeguards. It is nearly complete, though it omits guidance for confirmPlanHash and laneSource.

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 80%, and the description adds meaningful semantics beyond the schema: apply controls preview versus write, readDeck has fallback behavior unless reference/surface/section.width are given, and codeChange has a destructive side effect. It still leaves some parameters such as laneSource and confirmPlanHash unexplained in prose.

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 clearly states a specific purpose: CS454 assessment live loading using the plugin's own engine to lay out lanes, vehicles, moving load cases, and remaining areas. It is much clearer than a generic name restatement, though it does not explicitly distinguish this tool from the sibling cs454_lane_layout.

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 useful usage context: without apply it previews, with apply: true it writes, and the run can be undone via cs454_moving_loads_undo. It also says codeChange should only be used with the user's agreement, but it does not explicitly route the agent between this tool and sibling lane-layout 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, but the description goes further by disclosing that cleanup is selective: artifacts edited since the run or still referenced elsewhere are preserved. It also reveals the dry-run-by-default behavior. It stops short of saying what a cancelled/partial undo returns.

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 sentences, front-loaded with the destructive scope, then the retention caveat, then the preview switch. 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?

For a 2-param destructive tool with no output schema and no annotation beyond hints, the description covers the essential risk and behavior. The only real absence is any indication of what the preview output looks like or how a runId is obtained.

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 parameter meaning. It does explain `apply` semantics (preview unless true), but `runId` — the parameter that identifies which run's artifacts are removed — is never described, leaving half the surface to inference.

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 ('Removes') with an explicit resource set ('lanes, vehicles, cases and groups') and scopes it to artifacts written by a cs454_moving_loads run, which cleanly separates it from the sibling cs454_moving_loads and from generic undo tools like stages_undo.

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 use after a cs454_moving_loads run, but never states when to use it versus the many other *_undo siblings or what precondition (an existing runId) is required. 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?

Annotations already cover readOnlyHint and openWorldHint=false, and the description adds real behavioral content: it declares the exact row sources, the refusal condition, the four possible statuses (PASS / FAIL / BLOCKED / OUTSIDE RANGE OF VALIDITY), and that many rows make it run long as a website job. It doesn't cover output shape in detail, but that is largely a schema matter 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 core purpose, the force-row source, and the NOT CONCURRENT caveat are front-loaded in the first sentence; the trailing 'Read-only' and 'Takes a while' sentences earn their place. The first sentence is dense with parentheticals, but for a 23-parameter tool it is not wasteful.

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 23-parameter assessment tool with no output schema, the description covers what is assessed, where force rows come from, refusal behavior, and the status vocabulary returned. It omits any explanation of the utilisation values returned and the effect of some flags (e.g., secondaryActions), leaving minor 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?

Schema description coverage is 91% and the nested definitions are unusually thorough (links, rebar rows, stations). The description adds a little framing for cases and stations but mostly defers to the schema, so it does not need to carry parameter meaning itself.

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?

It states a specific verb and resource ('CS 455 ULS assessment of reinforced concrete beam sections') and names the checks performed (N–M flexure, shear, torsion cl 5.17–5.27) with per-row status output, which clearly separates it from siblings like cs455_describe_section or slab_assess.

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 operating context (reads concurrent force rows at chosen element ends for chosen combinations) and an explicit exclusion: a moving-load case from a model analysed without 'Normal + Concurrent Force' is refused as NOT CONCURRENT. It stops short of naming sibling alternatives such as cs455_describe_section or cs455_export_calc_sheet for those tasks.

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 readOnlyHint=true and the description's 'Read-only' is consistent. It adds real behavioral context beyond annotations: the outline is checked against published CIVIL NX properties, bars are placed with cover to every edge, and it returns both a drawing and derived values (area, centroid, depth, usable_for_capacity, per-row placement or failure reason). It does not detail error modes or what happens when section lookup fails.

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 workflow are front-loaded, but the description is one long run-on paragraph dense with parentheticals and schema-duplicating detail. Every sentence is arguably relevant, yet it is harder to parse than a short, structured summary would 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 6 parameters, nested rebar objects and no output schema, the description supplies a full picture of the return (drawing plus derived values) and the workflow around it. It is nearly complete for the call; it does not describe failure behavior for invalid section ids or the drawing format, which are the remaining 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?

Schema description coverage is 100%, so the schema already documents sectionId, image, rebar, restrained, concreteParts and confirmDimensions in detail. The description mostly echoes schema content (cover, rebar faces, return-values) rather than adding syntax; it does add intent for confirmDimensions ('only after the user has compared') and the restrained clause reference. Baseline 3 is appropriate given the schema does the heavy lifting.

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 title and first sentence state a specific verb+resource: read one beam section and place its bars, returning a drawing. It is clearly distinguished from siblings by naming cs455_export_calc_sheet as the reporting step and by describing the CS 455 placement behavior, so an agent can tell it apart 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?

'Start here when the user shares a reinforcement drawing, photo or schedule' gives an explicit trigger, and the follow-up 'then cs455_export_calc_sheet gives the report' names the next step. It also instructs to ask the user about anything missing (e.g. cover), covering when-not-to-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 already declare readOnlyHint=true and openWorldHint=false, and the description adds useful behavior beyond that: it writes an .xlsx workbook, includes live formulas/charts, returns a download link, and is read-only on the model. It does not contradict the annotations and adds substantial output-side context.

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 dense but well targeted, listing the workbook contents and return behavior without repeating the schema. 'The report.' is slightly vague as an opener, but the rest is front-loaded and earns its place for a complex export 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?

For a 25-parameter export tool with no output schema, the description explains the generated workbook's contents and that it returns a download link, plus the key prerequisite about rebar/links confirmed by cs455_describe_section. It is largely complete, though it could say more about file handling or failure behavior.

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 76%, so the schema already documents most parameters in detail, including many nested rebar and links fields. The description adds contextual guidance about reusing confirmed rebar/links, but it does not explain the many optional parameters or their interactions beyond what the schema provides, making 3 the appropriate baseline.

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 action and output: assess one element end exactly as cs455_assess and write the plugin's reference-format .xlsx calculation sheet, returning a download link. It clearly differentiates this export/report tool from the assessment sibling by naming cs455_assess and detailing the Excel output contents.

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 operational context: use the same rebar/links that cs455_describe_section confirmed against the user's drawing, and notes it is read-only on the model. It does not explicitly state when to choose this over cs455_assess versus merely viewing assessment results, but the report-generation purpose is strongly implied.

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 readOnlyHint, it discloses that output is always download links, never files inline, and that the tool runs as a job. It also flags a real side effect: although read-only, snapshots make CIVIL NX show each stage in turn. The main gap is that job polling and result-retrieval behavior are not described.

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 return behavior, and every sentence contributes. The first sentence is very dense with an exhaustive report-content list, and the job sentence is extremely terse given the importance of job semantics.

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 9-parameter job tool with no output schema, it covers the output artifacts, side effects, and many parameter behaviors well. It still leaves two important gaps: how to retrieve the job result/status and what view controls in the generated pictures.

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%, and the description adds useful meaning: series defaults to Summation, members adds a beam result component as in cs_stage_results, snapshots create stage pictures, maxSnapshots spreads pictures across many stages, and program is a fallback label. It omits explanation of view and only implicitly covers displacements.

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 makes the Construction Stage Reporter plugin's reports of construction stages and returns Excel/PDF download links. It also names the precise report contents and explicitly distinguishes the unavailable MP4 output, so an agent can identify the tool without inspecting 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?

It gives one useful exclusion (MP4 is not available here; use the CIVIL NX plugin) and a prerequisite (displacements are included when the analysis has been run). However, it does not say when to choose this report over siblings like cs_stage_summary, cs_stage_results, or export_result_tables, nor does it explain how to poll the job.

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 readOnlyHint, it discloses important behavior: stages after the analysis stopped carry the previous stage and are flagged published:false, composite members' stresses are read per section part, and the call 'may take a minute on big models'. It also states which endpoint family is used and the units, which is real context an agent could not infer from 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 content is dense and nearly every clause carries information, but it is delivered as one long run-on paragraph with nested parentheses and semicolons, which hurts scannability. It is appropriately sized for the complexity, though the structure could be broken into clearer sentences.

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 a 6-parameter tool with a nested members object and no output schema, the description covers the return shape (per-stage |D|, node, DX/DY/DZ; beam max/min, element, I…J position, section part), units, defaults, prerequisites, and degraded-stage behavior. An agent has enough to call it correctly without further 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 description coverage is already high (83%), but the description still adds meaning: it explains that displacements default on, that nodes:[ids] adds those displacements per stage, that detailElements ≤20 adds values along beams, and that series defaults to Summation and can be enumerated via listSeries. That goes beyond what the schema's brief property descriptions 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?

The description gives a specific verb and resource ('Reads construction-stage analysis results') and details exactly what is returned for displacements (largest resultant |D| per stage, node, DX/DY/DZ) and members (beam forces/stresses with element, position, section part). It does not explicitly name or contrast with siblings like cs_stage_report or cs_stage_summary, so it falls short of full sibling differentiation.

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 states the prerequisite clearly ('Needs a construction-stage analysis already run in CIVIL NX') and explains the defaults for displacements, series and listSeries. However, it never says when to choose this tool over cs_stage_report or cs_stage_summary, leaving the main alternative-selection question unanswered.

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=true and openWorldHint=false, and the description's 'Read-only' is consistent with them. Beyond that it discloses substantive behavior: it runs the plugin's engine against the currently open model, and it returns built-in consistency checks (a group deactivated before activation, unused groups, elements never activated) — an agent would not guess these from 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 the verb and scope, then dense enumeration where nearly every clause adds a distinct output category. It is one very long sentence with nested parentheticals and a trailing ellipsis, which costs some readability but 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?

With no output schema, the description carries the full burden of describing returns and does so thoroughly per stage plus model-level summary and consistency checks. Gaps remain around the maxStages truncation behavior and any precondition failure mode (plugin missing, no model open).

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%, so the baseline is 3. The description explains what elementIds and groups add to the output, but that largely repeats the schema descriptions, and 'stages' and especially 'maxStages' (no schema description, cap 500) receive no explanation of behavior such as truncation when the default of 150 is exceeded.

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 ('Reads the construction stage definition of the open CIVIL NX model') and enumerates the exact per-stage content returned. It is distinguishable in substance, but it never names or contrasts itself with close siblings like cs_stage_report, cs_stage_results, construction_stages, or stage_groups.

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 when-to-use/when-not guidance and no alternatives named, despite four adjacent stage-related siblings. The only implicit context is 'the open CIVIL NX model with the Construction Stage Reporter plugin's engine', which hints at a prerequisite but never states it as a usage condition.

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 annotations, the description discloses important behavior: it is a job that takes minutes on the website, it can be refused when the open model's counts differ, it conditionally runs analysis, and it returns the verdict and governing locations. These details materially help the agent understand runtime and failure conditions.

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 dense but appropriately sized for a complex check-running tool, and it front-loads the prerequisite before listing the checks. Every sentence carries useful information, though the long check enumeration makes it less compact than an ideal 5.

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, nested-parameter tool with no output schema, the description explains the operation, duration, refusal condition, and high-level return. It leaves some ambiguity about whether the call blocks or returns a job identifier for later polling, but overall it is complete enough 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 100%, so the baseline is 3. The description reinforces the analyse:false behavior but adds little to the detailed parameter schema, and it does not mention maxLocations semantics beyond the schema's own description.

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 runs the CIVIL NX analysis, reads basic-case results, and runs the plugin's checks on the culvert model. It clearly scopes the operation to Annex A2 combinations and vehicle positions, distinguishing it from build/preview/report siblings even without naming 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?

The description gives clear usage context: it operates on the culvert model built from the same inputs and is refused if the open model's counts differ, and it explains the analyse:false option. It does not explicitly name alternatives or state when to choose this over culvert_preview, culvert_report, or job_status.

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 readOnlyHint=false, but the description adds real value beyond them: the write-then-read-back verification that fails if CIVIL NX drops any loads, the empty-model guard, and the explicit warning that newDocument replaces the open model and loses unsaved work. It does not cover rollback semantics or mention the accompanying undo 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?

Three dense sentences, front-loaded with what gets built, then the safety constraint, then the preview default. The long enumeration earns its place because it defines scope, though the preview/apply note is somewhat buried at the end rather than stated up front.

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 destructive, deeply nested build tool with no output schema, the description covers the what, the safety profile and the verification behavior. The gaps are the unexplained confirmPlanHash workflow (presumably tied to a prior plan/preview step) and the absence of any reference to culvert_build_undo or how to recover from a bad build.

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%, and the description compensates for apply and newDocument (preview default, destructive replacement). However, confirmPlanHash is never mentioned in either the description or the schema, leaving a meaningful parameter entirely opaque on a destructive tool, and the nested project object relies wholly on its own schema text.

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 concrete verb plus resource ('Writes the 2D Culvert model') and enumerates the exact contents written: units, material, sections, frame, soil springs, supports, load cases and EN 1990 Annex A2 combinations. It is unambiguous what is produced, though it never names the sibling preview/undo tools to sharpen the boundary.

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 operating conditions precisely: 'into the open model only if it is empty, or into a new document (newDocument: true)' and 'Previews unless apply: true', so the agent knows the preconditions and the dry-run default. What is missing is an explicit pointer to culvert_preview / culvert_build_undo as the alternatives for previewing or reverting.

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, but the description adds the substance the annotation cannot: exactly which record groups are deleted (combinations, loads, load cases, springs, supports, groups, elements, nodes, sections, material), that model units are restored, that preview is the default, and one irreversible edge case. That is precisely the what-gets-destroyed context a mutating tool 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?

Three sentences, front-loaded with the destructive scope, then the limitation, then the preview/apply rule. The parenthetical list is long but each item is informative 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?

For a two-parameter destructive mutation with no output schema and full annotation coverage, the description covers scope, reversibility, and preview behavior adequately. The remaining gap is runId semantics and what the returned preview looks like, though no output schema exists to relieve that.

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 the parameter burden. It explains apply well ("Previews unless apply: true"), but runId is never mentioned — an agent cannot tell from this text that runId selects which build run to revert, nor what happens if it is omitted.

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 (deletes rows) applied to a precisely named resource (everything culvert_build wrote), and enumerates the record types touched. Naming culvert_build ties it to its counterpart sibling, so an agent can distinguish this undo tool from the other *_undo tools in the 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?

"Previews unless apply: true" tells the agent the default invocation is a dry run, which is direct usage guidance, and "A model replaced by newDocument cannot be brought back" states an explicit exclusion where the tool is useless. What is missing is a plain statement of when to reach for undo versus rebuilding with culvert_build.

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=true and openWorldHint=false, so safety is covered. The description adds substantial behavioral context by enumerating what the preview returns (nodes, elements, springs, load cases, combination counts, check locations, earth-pressure basis, derived geometry) and clarifying that no model is required. It does not describe failure behavior or validation-error output, which keeps it from a 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?

The description is front-loaded with the core purpose and then packs the return contents densely. It is a long sentence, but every clause appears to carry useful information and there is no obvious 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?

With no output schema and only one optional parameter, the description carries most of the explanatory burden and does so by listing the returned artifacts. Combined with read-only annotations, this is nearly complete, though it could clarify the exact response shape or validation-failure behavior.

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 nested project parameter is fully documented in the schema, including default merging and array replacement semantics. The description adds no meaning beyond the schema for the parameter, so the baseline of 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: it validates a 2D Culvert project using the plugin's Eurocode core and returns the generated model data. This clearly distinguishes it as a preview/dry-run tool, though it does not explicitly name sibling tools like culvert_build or culvert_analyse_and_check.

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 phrase 'Needs no model' implies this is a pre-build validation step, which gives implied usage guidance. However, the description never states when to use this versus culvert_build, culvert_analyse_and_check, or culvert_report, nor does it explicitly exclude use cases.

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=true and openWorldHint=false, but the description adds useful behavior: the report is generated from one run of the checks, xlsx is the default, result diagrams are captured from CIVIL NX, and download links are returned. The phrase 'writes the plugin's report' sits slightly awkwardly with readOnlyHint=true, but it appears to describe artifact creation rather than model mutation.

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?

It is a single front-loaded sentence that covers the main action and output formats without filler. It is dense but appropriately sized for a report-generation tool, though the parenthetical about culvert_analyse_and_check interrupts the flow.

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 correctly notes that download links are returned. It covers the key behavior for the format and analyze parameters, while the large nested project parameter is left to the schema's detailed 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 67%, so the schema already documents the format enum and most of the project structure. The description adds the xlsx default and clarifies that 'both' comes from one run of the checks, but it does not explain the analyze flag's full effect or elaborate on the project merges beyond what the schema already says.

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 output: runs checks on the analysed culvert model and writes the plugin's report in xlsx, pdf, or both. It explicitly contrasts itself with culvert_analyse_and_check, so an agent can distinguish the two 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?

It clearly says the checks run as in culvert_analyse_and_check and that re-analysis happens only when analyse: true. That establishes the main usage condition and names the sibling alternative, though it does not mention when to prefer other report-oriented siblings such as model_report_export.

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 destructive and open-world, and the description backs that with concrete consequences: new ids only, existing rows never overwritten, default material/section/thickness created or reused, a master group DXF_<file> #<token> created, a read-back verification, and a journal enabling exact undo even after partial failure. The write ordering and the destructive unit switch are disclosed, so the agent knows exactly what state is touched.

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 behavior, the preview-by-default contract, and the write sequencing are front-loaded before secondary details, and every sentence carries operational content. It is dense for a several-sentence paragraph but not padded.

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, yet the description explains what the preview returns (plan with id ranges, groups, default properties, any unit switch) and what the write does end to end. For an 18-parameter, nested-object mutation tool this covers the safety contract, verification and rollback path an agent needs.

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 parameter documentation burden is already met by the schema (including the detailed mapping example and the destructive matchModelUnits note). The description adds only a pointer that inputs mirror dxf_inspect plus mergeExisting, without new semantics, so baseline 3 applies.

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 concrete verb and resource ('Imports a DXF into the open CIVIL NX model') and names the engine (Advanced DXF Importer plugin). It also draws the boundary against siblings: it references dxf_inspect for inputs and dxf_import_undo for reversal, so the agent can tell what this tool does and does not cover.

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 two-step workflow is explicit: preview by default (writes nothing), then call again with the same inputs plus apply:true and confirmPlanHash, with the write refused if the plan changed. What is not resolved is when to use this tool's preview versus dxf_inspect, which the description only cross-references by 'Inputs as for dxf_inspect' without saying which to reach for first.

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 destructiveHint/openWorldHint annotations, disclosing the exact deletion order (elements then nodes), the fingerprint guard that preserves anything edited since the import, the rule keeping nodes still used by other elements, and the conditional unit restore. The only gap is the shape of the non-preview response, but the annotations already flag destructiveness and the description adds rich behavioral context.

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-loads the core action in the first clause and packs the rest with substantive rules rather than filler. It is dense and long, but each clause carries a distinct behavioral fact; slight tightening of the nested parentheticals would help 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 destructive two-parameter tool with no output schema, it covers preconditions, default targeting, safety behavior, and what the preview reports. Only the committed-run return value is left implicit, which is a minor gap given the preview is described.

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 50% (apply has no schema description), and the description compensates by explaining that apply: true commits while the default previews what would be removed and kept. It also explains the runId default (latest un-undone import), giving meaning beyond the schema's "The runId dxf_import returned."

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 ("Removes what one dxf_import created") and immediately frames it as an undo of a named sibling, so the agent can distinguish it from dxf_import, dxf_inspect, and unrelated *_undo tools. The scope statement is precise about what is removed and under which rules.

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 preconditions and exclusions: it "refuses unless the import's master group is in the open model," works after a partial import, and defaults to the latest not-yet-undone import when runId is omitted. It also spells out the safe path — preview by default, mutate only with apply: true — leaving nothing to inference about when to call it.

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 and openWorldHint; the description adds genuinely new traits — no model required, nothing is changed, and concrete input ceilings (4 MB inline, 25 MB by url). It also notes that report lengths follow the import's working unit, which matters for interpreting results. It stops short of discussing errors or performance on large drawings, so not a 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 purpose and scope, then report contents, then the dxf_import hand-off, then input options and the units caveat. Dense but every clause carries information; the source-inputs sentence is the only part that largely duplicates the schema.

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 the necessary work by enumerating what the report contains (version, encoding, entity counts, ignored/unsupported items, layers, elements, structure groups, disconnected parts, clean-up operations). That is enough for an agent to know what it will get back; the reference to 'importIn' as a unit, which is not among this tool's parameters, is the one loose end.

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 100%, so the baseline is 3. The description restates the three input sources and their size limits (already in the schema) and adds the unit framing ('Lengths in the report are in the unit the import works in (importIn)') — but 'importIn' is not a parameter of this tool, which slightly muddies rather than clarifies parameter meaning.

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 (reads a DXF with the plugin's parser) and names the exact output shape: what an import would create — file metadata, units, layers/mapping, and the clean model. It is unmistakably a dry-run sibling of dxf_import rather than a conversion.

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 routing: 'Use it to choose the mapping and settings before dxf_import', plus the scope qualifier 'Needs no CIVIL NX model and changes nothing' that tells the agent this is the safe pre-flight step. The alternative (dxf_import) is named and the selecting condition is 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?

Goes well beyond the annotations: it discloses the dry-run-by-default behavior, the write pattern (one element written and read back first, then the rest), and the direction audit — meaningful safety context for a mutating tool flagged readOnlyHint=false. This is exactly the operational detail annotations cannot express.

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 calculation and the write target, then the mechanics and the preview switch. It is dense and em-dash-heavy but every clause carries information; a light restructuring would improve scanability without cutting content.

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 no-output-schema mutation tool with 18 params and nested geometry, it covers the essentials: what gets written, where, in what order, and that it previews by default. Gaps remain around overwrite behavior for existing EC1W_ cases, failure/rollback semantics, and the purpose of confirmPlanHash, which an agent would need before a real apply.

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 18 parameters at 56% schema coverage, the schema carries most of the burden. The description adds real value on target selection (elementIds vs group vs implicit deck) and the directions default of all six, but says nothing about co, vb0, nationalAnnex, terrainCategory, confirmPlanHash, or cscdOverride, leaving several params 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 and resource ('Calculates §8 wind on the deck and writes it with the Eurocode Wind Loads plugin's adapter') and specifies the concrete output artifacts: one EC1W_ load case per global direction plus beam loads or pressure + fascia nodal loads. An agent can distinguish this write operation from read/remove siblings without opening 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 'Previews unless apply: true' clause is an explicit usage condition and the target-resolution rule (elementIds, group, or default deck) tells the agent what inputs select which target. It stops short of naming alternatives such as ec_wind_bridge for geometry-only calculation or ec_wind_remove for cleanup.

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=true and openWorldHint=false; the description adds that calculation is standalone ('Needs no model'), uses the plugin's own engine, and returns derived forces and load cases. It does not discuss failure modes or out-of-scope structural forms, but it does not contradict 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 definition is a single front-loaded sentence with no filler, and 'Needs no model' appears early. The dense symbol list is justified because there is no output schema, though readability could improve by separating purpose from returned quantities.

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, listing v_b, q_p(z_e), c_sc_d, d_tot, component forces, and load cases fills a real gap. Required bridge geometry and many defaults are covered by the schema, while limitations such as out-of-scope structural forms are left to schema fields rather than 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?

The description contributes almost no input-parameter meaning; it lists outputs and says no model is needed, but several schema parameters lack descriptions and the description does not compensate. At 58% coverage, the agent must infer several units, defaults, and enum meanings from parameter names.

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 (Calculates), exact standard/resource (EN 1991-1-4 §8 wind actions on a bridge deck), and names returned quantities. 'Needs no model' separates it from model-bound siblings such as ec_wind_apply, so an agent can identify the tool without opening 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?

Provides a usage condition ('Needs no model') but does not name alternatives or exclusions, such as when to use ec_wind_apply for writing into a model or ec_wind_read_deck for reading deck data. The guidance is implied rather than explicit.

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=true and openWorldHint=false, so safety is covered; the description still adds real value by listing the returned quantities (there is no output schema) and flagging that the structural form is only a 'guess'. It does not disclose failure behavior, e.g. what happens when no deck can be found or how ambiguity between candidates is resolved.

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 dense sentence, front-loaded with the verb and the 'finds the deck' core, followed by a compact colon-list of outputs. Nothing is padding, though the output enumeration runs long 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 no output schema, the description usefully enumerates what comes back, and annotations cover the read-only profile. Gaps remain for a measurement tool: units/conventions for b, d, L and soffit height are unstated, and no-deck-found behavior is not described.

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 compensate, and it does partially: 'measures the elements / group given' assigns a role to each of the two parameters. However it leaves precedence undefined (what happens if both group and elementIds are supplied), does not explain what a 'group' string refers to, and does not say both are optional.

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 ('Reads the open model ... finds the deck') and enumerates the exact quantities it reports (b, d, L, soffit height, span axis, deck type, structural form). It is clearly a read/measure step in the ec_wind_* family, distinguishable from ec_wind_apply and ec_wind_remove, though it does not name 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?

Usage is implied rather than stated: an agent can infer this is the survey step before ec_wind_apply, and the parenthetical hints that passing a group or elementIds switches to measuring those instead of auto-finding the deck. There is no explicit when-to-use/when-not statement or guidance on choosing between the two modes.

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 readOnlyHint=false, but the description adds substantial context: exactly which load cases and load groups are removed, that plugin-window-authored loads are also removed, and that unrelated loads on the same elements are preserved. It also discloses the preview-by-default behavior, which is valuable for a destructive operation.

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 sentences, front-loaded with the removal scope, followed by the preservation guarantee and the preview/apply rule. Every clause adds useful information with no 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?

For a destructive one-parameter removal tool with annotations and no output schema, the description covers what is removed, what is preserved, and the preview/apply distinction. An agent has enough information to invoke it 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 only parameter is apply, and although schema description coverage is 0%, the description explicitly states 'Previews unless apply: true.' This fully explains the parameter's effect beyond its boolean type and default value.

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 removes every EC1W_ load case, load group, and their beam/pressure/nodal loads written by the Eurocode Wind Loads plugin. It distinguishes this from sibling tools by naming the plugin provenance and clarifying that loads from other sources are kept.

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 default preview behavior and the apply: true mutation path, so an agent knows how to invoke it safely. It does not explicitly name alternatives such as ec_wind_apply or state when not to use this tool, but the intended use context is 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?

The annotations only state readOnlyHint=true and openWorldHint=false. The description adds substantial behavioral detail: one sheet per table, splitting above 1,048,575 rows, unit-labelled headers, a Contents & Export Log sheet, download links returned instead of inline files, partial failure isolation, and long-running job execution. This is rich context beyond the structured 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 front-loaded with the core export behavior and remains dense with operational details such as sheet layout, failure logging, and download-link returns. Its length is proportionate to the complexity of a multi-table export tool, and every clause provides useful 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, but the description states the return shape (download links and a per-table summary), covers partial failure behavior, and notes that long-running exports execute as a job. Together with the annotations and schema, this gives an agent enough context to invoke 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 50% schema description coverage, the description compensates by explaining that each entry in the 'tables' array mirrors preview_result_table arguments with full scope and no sampling, and that format='csv' changes the output to one CSV file per sheet. It does not explain workbookName or includeContents directly, but those are covered by schema descriptions, so the main semantic gap is filled.

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 uses a specific verb and resource: it exports CIVIL NX tables into an Excel workbook or CSV files. It also distinguishes this from preview_result_table by stating that the export uses full scope and no sampling, so an agent can tell the two tools apart without opening 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 clearly establishes the export use case, explains that format='csv' produces one CSV per sheet instead of an Excel workbook, and warns that large models run as a job. It does not explicitly name when to avoid this tool or route the agent to a preview alternative beyond the schema's 'preview first' note, so it falls 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 already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds genuinely new behavior: partial progress reporting before completion, result delivery only on finish, and the two terminal states done/failed. It doesn't cover intermediate state names or whether repeated polls are rate-limited, keeping it below a 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?

Two sentences, both front-loaded: what is returned first, then how to poll. Every clause carries information (return fields, timing, termination); nothing is redundant with the annotations or schema.

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 one parameter, no output schema, and read-only annotations, the description covers what an agent needs: where jobId comes from, what comes back over time, and when to stop polling. Remaining gaps are minor — the full set of non-terminal state values and error/failure payload semantics are unstated.

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% (jobId is typed as a bare string with no description), so the description must compensate — and it does, explaining that jobId is the identifier returned by the original long-running tool call. It still doesn't say whether jobId is opaque, session-scoped, or whether it expires, so not a full 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 set (report status, progress, and result) against a specific resource (a tool call identified by jobId). The precondition 'a tool call that returned a jobId' uniquely identifies this as the async-polling tool, distinguishing it from the many analysis/setup siblings without needing a named alternative.

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 invocation guidance — 'Poll every few seconds until status is done or failed' — including cadence and the stopping condition, plus the implied trigger (a prior call returned a jobId). It stops short of saying what to do on a failed status (retry vs. abandon) or what not to do, so it is clear context rather than full when/when-not routing.

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=true and openWorldHint=false, so 'Read-only; writes no file' is largely reinforcement rather than new information. What the description does add is substantive: the tool reads both model geometry tables and CIVIL NX-computed section properties, reports area differences against CIVIL NX, and surfaces excluded weightless members — behavior an agent could not infer from 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 scope is front-loaded in the first clause and the usage routing comes last, so an agent gets the point immediately. The middle sentence is a very long comma-delimited inventory of reported items that is dense but each item earns its place as return-value disclosure.

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 carries the full burden of describing return content — and it does so exhaustively (girder lines, foundations, bearings, alignment fit, per-section area deltas, volumes per material). With readOnly/openWorld annotations covering safety and all six parameters defaulted, nothing an agent needs to call it correctly 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 100%, so all six parameters are already documented in the schema. The description echoes several of them indirectly (tendons, 'the joined deck', 'weightless members left out', 'every section in use'), but adds no syntax, units, or default behavior beyond what the schema states. Baseline 3 applies.

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 opens with a specific verb-plus-resource ('Reads the open model's geometry tables and CIVIL NX's computed section properties') and enumerates exactly what it reports: girder lines, piers/pylons, abutments, bearings, deck alignment and line/arc fit, joined deck, sections with outline rebuild and area deltas, tendons, weightless members, volumes. It is unmistakably the diagnostic/preview counterpart of model_to_ifc and cannot be confused with any sibling.

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 trigger conditions directly: 'Use it before model_to_ifc / model_to_dxf, or to sanity-check a model.' That names the alternatives and the ordering, and the 'Read-only; writes no file' clause makes clear why one would pick this tool over the exporters.

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 readOnlyHint already present, it discloses the read scope (only the tables the checks use), the async job behavior on the website, and — with no output schema — enumerates each check's returned result fields (pass/fail/not-applicable/not-run, severity, criterion, count, ids), the model summary, and the table-read record. This is substantive behavioral context the annotations 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?

Purpose and scope are front-loaded, and the long enumeration of the fourteen checks earns its space by defining coverage. The return-value clause is a dense run-on that could be tightened, keeping it from a 5.

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, no-output-schema tool, the description is complete: it explains what is checked, the read-only/GET/job behavior, and the shape of the returned results and summary. An agent has enough to decide to call it and to 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 coverage is 100% with clear descriptions for all four parameters, so the schema already does the work and the baseline 3 applies. The description adds no parameter-level detail (e.g. how toleranceMm interacts with the coincidence check beyond what the schema says).

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 (runs fourteen quality checks) on a specific resource (the open CIVIL NX model) and enumerates what is checked, so an agent knows exactly what the tool covers. It is clearly distinct from siblings like model_report_export or model_report_images, which handle output rather than checking.

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 establishes the operating context (the open CIVIL NX model), notes it is GET-only, and mentions that on the website it runs as a job. It does not explicitly name when to prefer a sibling (e.g. model_report_export after running) or state exclusions, so it falls short of the explicit alternative-routing a 5 requires.

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 readOnlyHint=true and openWorldHint=false, but the description adds substantial behavioral context beyond those hints. It discloses that the tool runs as a job, that CIVIL NX renders pictures via POST /view/CAPTURE while leaving the user's view unchanged, that it otherwise performs reads including POST /post/TABLE for tendon coordinates, and that beam diagrams and tendon coordinates require an analysed model.

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 remains dense with relevant detail. It is appropriately sized for a complex export tool, though the single long paragraph could be split for 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?

Given the tool's complexity and the absence of an output schema, the description explains that the result is download links, the available formats, and job execution. It is largely complete, but it does not describe how to retrieve job status or results, and it omits explanation of the QC tolerance and outlier parameters.

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 88%, so the schema already documents most parameters. The description still adds useful semantics: default picture behavior (modelViews ['iso'], savedFigures 'all'), legend formatting for beam diagrams, the need for an analysed model, and where document details appear. It does not explain toleranceMm or outlierFactor, which are only 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?

The description states a specific verb ('Builds') and resource ('the Model Report plugin's Model report') and enumerates the report's contents, output formats, and supported languages. It also names the sibling tool model_report_images for picture keys, so an agent can distinguish this export from related report tools.

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 context: reports on the open CIVIL NX model, returns download links, and runs as a job. It also explains image defaults and points to model_report_images for available picture keys. However, it does not explicitly compare against alternatives such as export_result_tables or cs_stage_report.

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 and openWorldHint=false; the description adds the useful clarification that it is GET-only and that 'nothing is rendered', telling the agent no image generation side effect occurs. It does not cover failure modes such as a model with no saved figures, keeping it short of a 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 verb and resource, and every clause enumerates a distinct category of returnable image, so the length is earned. The single long sentence with nested parentheticals is dense but not padded.

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 carries the burden of explaining the return value, and it does so by listing the image categories and key concepts. The exact key string format remains unstated, leaving a small gap for an agent that must construct keys, but the structural picture is sufficient.

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 has zero parameters, so the baseline is 4. The description compensates by describing the returned key space in detail (iso/plan/front/side views, per-static-case loads, /db/UFIG figures, per-case/combination/stage diagram components Fx…Mw), which is more than the empty 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 a specific verb and resource — lists the CIVIL NX pictures the Model Report can carry, with their keys — and enumerates exactly what kinds of images appear (FE views, load figures, /db/UFIG figures, beam diagrams). It also distinguishes itself from the sibling model_report_export by positioning itself as the catalogue that export consumes.

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?

Explicitly routes the agent: 'Pick from them with model_report_export images' names the alternative tool and the follow-up action. It implies the intended flow (discover keys here, then export) but does not state any exclusion such as when not to call it.

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=true and openWorldHint=false; the description reinforces this with 'Only reads the model; returns download links.' It also adds genuine behavioral context beyond annotations: cut coordinate conventions in metres, the default cut when none is supplied, the effect of cutsAtSupports, and the max3dMegabytes skip 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?

Front-loaded with the core purpose and the two output types, then the cut syntax, then the read-only/download-link note. It is dense and long, but for a 17-parameter tool nearly every clause carries distinct information; a few items (e.g. drawings2d, name) are left to the schema rather than repeated.

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 17 parameters and no output schema, the description does the important work: it explains the cuts structure, default and support-cut behavior, the 2D/3D outputs, and that results come back as download links. Some parameters (drawings2d, name, wireframe interplay) are left entirely to the schema, but nothing an agent needs to call it correctly 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 coverage is 82%, so the baseline is 3, but the description meaningfully extends semantics for the undocumented 'cuts' array: kinds (cross/long/level) with their reference frames, 'at' in metres, and 'depth' meaning how far beyond the cut to draw. It also clarifies units labeling (m/ft for levels and chainages) beyond the schema's own enum description.

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: draws the open CIVIL NX model as DXF, producing both a 2D drawing (DXF 2000, with plan/elevation/iso/cuts/sections) and a 3D polyface-mesh DXF. It explicitly ties itself to the Model to IFC plugin's drawing engine, which separates it from siblings like model_to_ifc (IFC export) and dxf_import (opposite direction).

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 rather than spelled out: the tool reads the model and returns download links, and cut defaults ('none given = one across mid-span, cutsAtSupports adds one at each pier') give context on how it behaves by default. However, there is no explicit statement of when to choose this vs model_to_ifc, model_report_export, or dxf_inspect, and no prerequisites or exclusions are named.

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 readOnlyHint annotation, the description states that it only reads the model, returns download links rather than inline files, includes the exporter report, and runs as a job because large models can take a long time. These are operationally important details an agent would otherwise have to infer.

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 dense with relevant information, which suits a complex export tool. The long semicolon-separated sentence is slightly harder to scan but does not waste space on repetition.

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 21-parameter export with no output schema, the description covers purpose, schema choice, optional analysis content, return format, job behavior, and runtime caveats. An agent has enough information to decide whether and how to call 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 already 90%, so most parameter meaning is carried by structured fields. The description adds useful context around resultSeries, deformed output, and IFC4.3 bridge content, but it does not meaningfully explain many of the 21 parameters beyond what the schema already 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 begins with a specific verb and resource: exports the open CIVIL NX model to IFC via the Model to IFC plugin. It clearly distinguishes this from unrelated siblings by being an IFC export, not a DXF or report export.

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 makes the IFC4 vs IFC4.3 choice explicit and explains what each schema adds, while also clarifying that analysis results and deformed-shape output are optional. It does not name sibling alternatives such as model_to_dxf, but the intended use case is still 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful context: it uses the plugin's own engine, performs applicability checks, requires no model, and returns the four states with force, peak pressure, resultant and moment per metre. It does not specify persistence behavior, but the model-free note and read-only hint make that clear enough.

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 packs the key differentiators (Route A, no model, four output states) into a single dense sentence. It is appropriately sized for a complex calculation tool, though it could be split for readability; no sentence is purely 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?

For a complex 20-parameter tool with no output schema, the description covers the high-level purpose, route conditions, no-model requirement and the four output states. However, it leaves most parameter semantics to a schema with only 45% coverage and does not fully explain the return object structure. It is minimally adequate but has clear gaps for 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 description coverage is only 45%, so the description should compensate for the many undocumented parameters. It broadly mentions thermal movement, design displacement, route, coefficients and states, but does not explain the roles of parameters such as psi, gammaQ, skewDeg, gammaSat, gammaBulk, surchargeKpa, hasWaterTable, waterTableDepth, phiInferiorDeg, phiSuperiorDeg, nAbutmentsSharing and others. The description adds high-level grouping but not sufficient per-parameter meaning for a 20-parameter tool.

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 calculation: PD 6694-1 integral abutment earth pressures via the limit-equilibrium route (K*, cl.9.4.3/9.4.4), naming the engine and the four output states. It distinguishes itself from siblings by specifying Route A/A1/A2 versus B/Annex A review and by noting it needs no model, which separates it from model-dependent SSI or write tools.

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 a clear condition for Route A versus Route B / Annex A review, and states that the tool needs no model. It does not explicitly name the SSI or write/remove sibling tools, but the alternative route condition and the model-free scope provide enough context for an agent to select it correctly.

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 destructiveHint annotation by naming exactly what is destroyed (four load cases, pressures, load groups, stage activations) and confirming that other load cases are retained. It also discloses the preview-by-default behavior, which is critical for a destructive operation.

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 dense sentence that front-loads the removal scope and ends with the safety-relevant preview condition. Every clause carries useful information with 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?

For a one-parameter destructive mutation with annotations covering the safety profile, the description gives nearly everything an agent needs: scope, retention of other cases, and preview behavior. It does not mention reversibility or undoability, which would be useful context for a removal 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 0% schema description coverage, the description compensates by explaining that the sole parameter apply toggles between preview and actual removal. That meaning is clear, though minor details such as the type/default are left to the schema (boolean, default false).

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: removes the four PD6694 EP limit-equilibrium load cases, including pressures, load groups and stage activations. The parenthetical '(the plugin's Remove)' and the scope note 'Other load cases are kept' distinguish it clearly from related route A and SSI tools.

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 a clear operational context: it is the plugin's Remove command and previews unless apply: true. It does not explicitly name an alternative sibling such as pd6694_route_a_write or discuss when not to use it, but the intended use is unambiguous.

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