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

Annotations declare destructive/open-world/non-idempotent, and the description goes well beyond them: model-state guards persist, the selected method may overwrite/delete or trigger external effects, unsupported routes and failed calls are errors, and a lost write reply has unknown outcome with no automatic rollback, so objects must be inspected before retry. Nested branch docs add permission tiers, update_model commit semantics, and cascade defaults for removals. No contradiction with destructiveHint=true.

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

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

The top-level description is front-loaded — purpose first, workflow second, hazard warning last — and every sentence carries a constraint. It is dense but justified for a destructive escape hatch; the very large nested branch documentation (

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

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

With an output schema present, return-value documentation is unnecessary, and safety hints are already in annotations, yet the description still covers auth/permission implications, state guards, forbidden methods, no-rollback retry policy, and the discovery prerequisite. Nothing an agent needs before invoking a destructive native call 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 100%, so baseline is 3; the description lifts it by saying kwargs are native backend parameters with method-specific units, that field names must not be translated, that signatures must not be invented or units inferred from another endpoint, and that operation distinguishes inspection from execution. These are genuinely useful usage constraints, though they are meta-rules rather than per-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 two-part verb+resource: discover installed qtmodel methods and call a native API, explicitly scoped to cases where "a dedicated domain operation does not expose the required feature." It separates itself from curated siblings and names the two sub-operations (list_qtmodel_api, call_qtmodel_api) plus the diagnostic sibling (inspect_bridge), so an agent can route without opening a schema.

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

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

Gives an explicit when-to-use condition (curated tool lacks the feature), an explicit preference/exclusion ("Prefer the relevant domain operation for supported tasks because it supplies typed arguments and engineering guidance"), a mandated two-step workflow, and a redirect for a related need (inspect_bridge for connection diagnostics). The nested branch docs reinforce this with a list of forbidden methods and their designated replacements.

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

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

Annotations declare destructiveHint=true and idempotentHint=false; the description earns credit by explaining why: configuration defaults overwrite prior settings, so prior setup is not preserved. It also discloses non-obvious runtime behavior — progress heartbeats, success only on a successful terminal state, read_timeout bounding the wait rather than the solve, and the fact that timeout does not cancel the computation. The disclaimer that neither a completed solve nor a confirmation implies code-check safety adds further value.

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

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

Purpose is front-loaded in the first sentence, and the length is defensible for a ten-operation dispatcher. However, the middle sections are dense and mix sibling routing, sequencing, timeout semantics and safety caveats without strong visual separation, making some sentences carry multiple ideas. Slightly tighter grouping 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?

An output schema exists, so return values need no explanation, and the description correctly focuses on what is missing elsewhere: per-operation routing, execution order, the no-solve-vs-solve distinction, and the overwrite caveat. For a dispatcher spanning configuration, dynamic inputs and solving, this covers everything an agent needs to invoke the right branch 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 single top-level parameter has 100% schema description coverage, and the per-operation sub-schemas document fields, units and defaults in detail, so the schema does the heavy lifting. The description's note that 'request.operation selects its own fields and units' largely restates the discriminator guidance already present in the schema. This meets the baseline for a well-covered schema without adding much beyond it.

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

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

The opening sentence names a specific verb+resource ('Configure and run structural analysis') and enumerates the concrete sub-domains it covers (masses, response spectra, time-history functions/cases, buckling). It also routes explicitly against siblings, noting query_results for solved responses, manage_checks for concrete verification, and access_backend for options lacking a dedicated operation. An agent can place this tool in the workflow 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?

States when to use it (after model, loads and stages are ready), when it does NOT act ('These configuration operations do not solve: choose run_analysis explicitly'), and names alternatives for adjacent concerns (configure_analysis, update_bulking_setting, query_results, manage_checks). Practical sequencing guidance is included ('read them first when preserving an existing setup', 'Check inspect_bridge before retrying').

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 non-idempotent, and the description reinforces this beyond the annotation alone: writes can overwrite supports/releases, remove constraints and change stability, there is no backup/undo/auto-solve, and the response is a confirmation rather than a verified saved definition. The most valuable addition is the warning that the same boolean means fix/couple/release in different branches, which 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?

Well front-loaded (purpose, then operation-selection routing, then semantic caveats, then write-safety warnings) and every paragraph carries distinct information. It is longer than average but the length is justified by the seven-branch discriminated union; only the embedded Chinese translations add some redundancy.

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 multi-branch mutation tool with an output schema present, the description covers operation selection, permission/existence prerequisites, boolean cross-branch semantics, overwrite behavior, readback guidance before analyze_model, and retry caution. 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 100% so the baseline is 3, but the description adds genuine cross-branch semantics the schema cannot: the identical boolean flag has three different mechanical meanings depending on the selected operation, and extra_parameters is enabled by default when supplied while extra_enabled=False clears it. This meaning-per-branch guidance materially aids correct invocation.

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 ('Edit mechanical boundary conditions on existing nodes and frame elements') and then enumerates the seven sub-operations by physical relationship (node-to-ground, node-to-node, frame end, weighted DOF). An agent can distinguish it from edit_geometry, edit_construction, and query_model 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 routes each case: node-to-ground uses set_support/add_elastic_support, node-to-node uses add_elastic_link/add_master_slave_link, and it names edit_construction and edit_geometry as the alternatives for their own concerns plus query_model for ID resolution. When-to-use and when-not-to-use are both covered.

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 destructive=true, idempotent=false and openWorld=false, but the description adds substantial non-redundant behavior: writes 'refresh the model, with no solve or automatic schedule rollback', group removal leaves model entities intact, and that a missing optional list differs from an explicit empty list. These are mutation-safety facts an agent cannot derive from the annotation hints alone, so it exceeds the lowered bar for annotated tools.

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

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

Purpose is front-loaded, followed by operation inventory, routing guidance, and semantics, with no filler sentences. It is dense and slightly prose-heavy for a 14-branch dispatch tool, but each clause carries routing or behavior information. A bulleted per-operation list would scan faster, which is the only reason it falls short of 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?

Output schema exists, so return-value explanation is unnecessary and the description does not waste space on it. For a 14-operation destructive dispatch tool it covers the prerequisites (referenced definitions must already exist), the empty-vs-missing trap, non-rollback, no-solve, and read-before/after practice. Nothing an agent needs to invoke a branch 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 100% and the per-operation branch schemas are themselves richly documented, so the baseline is 3. The description nonetheless adds cross-cutting semantics the schema does not state at the dispatch level: three separate group namespaces with exact-name references, empty-list vs omitted-list divergence, and the requirement that configure_operation_stage receive all four case-family lists with [] as an explicit disable.

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 domain verb ('Manage') over concrete resources (structure/boundary/load groups plus construction/operation-stage schedules) and names the activation/deactivation scope explicitly. It routes away from siblings by name ('Use edit_loads for physical loads and view_model for stage display only'), so an agent can distinguish it from edit_loads, edit_boundaries and view_model without opening the schema. The clause enumerating the constituent operations makes the dispatch surface unambiguous.

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

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

Explicit alternatives with conditions are given: edit_loads for physical loads, view_model for stage display only, and query_model for reading groups/stages 'before and after changing an existing schedule'. It also supplies a read-before-write workflow and distinguishes remove-a-group from deactivate-a-group and remove-a-stage from deactivate-in-a-stage. Nothing about when to reach for this tool is left to inference.

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

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

Adds substantial behavior beyond the annotations (destructive=true, idempotent=false): 'Writes require an editable model and can invalidate solved data,' 'Batch and workflow calls are not transactions: earlier writes can remain after failure,' and 'a confirmation is not always a readback.' These tell the agent about partial-failure risk and required readback, which the annotations do not. It stops short of a 5 only because per-operation specifics (already covered in nested schemas) carry much of the remaining 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?

Front-loaded with the verb/resource statement, then routing, then constraints, then write semantics - a logical order with no filler sentences. It is dense and clause-heavy in the routing paragraph, and the length is driven by legitimate complexity (22 branches), so it earns its size without being 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?

Covers everything an agent needs before calling a destructive, non-idempotent geometry editor: prerequisites (referenced entities must exist), enumeration-selection guidance, ID-assignment pitfalls, confirmation-vs-readback caveats, and the reminder that analysis is a separate step. Return values are handled by the output schema and the per-branch 'Returns:' blocks, so the description is complete for this complexity.

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, but the description adds cross-cutting meaning the schema does not: 'Referenced materials, sections and nodes must exist; plate thickness is distinct from a frame section,' 'Explicit IDs can be reassigned or reused by merging,' and the renumber pairing rule ('both paired lists, or neither for a global renumber'). The routing sentence ('Supply request.operation and that branch's fields') clarifies the discriminator contract.

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

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

States specific verbs and resources ('Create, edit, renumber, merge or remove model nodes and elements') plus the domain ('standard straight-girder workflows'), and it explicitly carves out sibling territory (edit_properties for materials/sections, edit_boundaries for supports, view_model for display). The only reason it isn't a 5 is that the top-level statement spans 22 discriminated operations, so the single 'purpose' is broad and only fully resolved by the nested branch schemas.

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

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

Gives explicit routing both internally and externally: 'Targeted update_element_* operations change one property; update_element edits a record. update_node sets absolute coordinates, move_nodes adds offsets, and renumbering changes IDs,' and 'Use edit_properties ... edit_boundaries ... view_model to change only the display.' It also closes the loop with 'Solving is a separate analyze_model operation,' leaving nothing to inference.

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

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

Annotations already declare destructive=true, idempotent=false, readOnly=false, but the description goes well beyond them: writes refresh the model and return confirmations without solving or activating a stage, calls can overwrite definitions or accumulate loads, there is no rollback of earlier calls, and the agent should query affected loads before retrying an uncertain write. That is precisely the operational 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?

Front-loaded with the routing bullets before the finer semantics, and the mutation/retry warning closes the definition where an agent needs it. It is dense and somewhat long, but for a thirteen-branch discriminated union almost every sentence corresponds to a real decision the caller must make, so little is wasted.

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

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

An output schema exists so return values need not be explained; the description still covers the write contract (refresh, confirmation, no solve, no stage activation, no rollback), unit-verification expectations, and the required follow-up (configure stages and solve). For a tool of this complexity 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% and each union branch carries its own parameter documentation, so the schema does the heavy lifting (baseline 3). The description adds cross-cutting meaning the schema does not: combination rows are [case_type, case_name, factor] with combine_type=1 adding effects and 3 forming an envelope, None/[] yields an empty definition, and 'case_name selects the load case; group_name selects its activation group' warns the two are distinct objects.

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

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

The opening sentence names a specific verb+resource ('Define static load cases/combinations and apply physical loads to existing nodes or elements') and the bullets enumerate all thirteen operations with their targets (nodes, frames, plates, plane patterns). An agent can tell the tool's scope apart from edit_prestress, edit_traffic and edit_construction purely from the description.

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

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

Explicit routing is given per operation ('create_load_case creates the case referenced by later assignments', 'apply_nodal_force targets nodes; apply_beam_distributed_load targets frames') plus explicit boundaries against siblings ('Use edit_prestress for named tendon loads and edit_traffic for vehicle/lane cases'). It also warns which cases are not what they look like ('A static "活载" category does not create a moving-load case') and clarifies the case_name/group_name distinction.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description goes well beyond them: it states no backup/rollback/analysis is performed, that writes refresh the model, that returns are requested names/load summaries rather than verified coordinates or effective prestress, that reusing a tendon name can replace complete geometry, and that load assignment is not a promise of idempotency, with a read-back-before-retry instruction. This is exactly the extra context annotations cannot 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 purpose, then operations, then caveats, which is the right order for a five-branch dispatcher, and each sentence carries information. It is nonetheless long and repeats the destructive/name-reuse warning across the top-level description and the nested branch descriptions, costing a little density.

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 multi-operation destructive write tool with an output schema, the description supplies everything an agent needs: branch selection, prerequisite ordering (material → property → geometry → element assignment → load), the fact that no analysis or rollback occurs, and the follow-up activation/analysis path. Return-value details are covered by the output schema, so nothing material is missing.

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

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

Schema coverage is 100% (baseline 3), and the description still adds cross-parameter semantics the schema states only in fragments: position_type flips point_insert from coordinates to [end, direction, element_id], num counts tendons rather than control points, apply_prestress accepts one name or a list, tension_type selects start/end/both, and force is forwarded without unit conversion against a verified export. These interactions materially improve correct invocation.

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

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

The opening sentence names the specific verb+resource (define named tendon paths and apply prestressing loads), and the bulleted list enumerates each of the five operations with a distinct verb (defines, places, matches, targets). It explicitly separates itself from edit_loads, manage_checks, query_model and query_results, so an agent can route 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 when-to-use rules are given per operation (create_tendon_property for mechanical/loss params, create_tendon_2d for planar profiles, add_tendon_3d for spatial paths, assign_tendon_elements to match elements, apply_prestress to target existing names in an existing load case), plus named alternatives for adjacent concerns (edit_loads, manage_checks, query_model, query_results) and a stated workflow order ending in edit_construction and analyze_model.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds material context beyond them: no automatic backup, rollback or solve; a definition change can affect many existing elements; requested IDs are not a guaranteed allocation result and must be read back via query_model; distinct ID namespaces for thickness vs section. This is exactly the 'what gets destroyed / what is not reversible' disclosure a mutation 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?

It is long, but the length is justified by a 17-branch polymorphic schema; the purpose is front-loaded and the middle is organized by branch family rather than prose bloat. Some routing sentences lightly restate per-branch schema descriptions, which keeps it short of 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 high-complexity write tool with an output schema, the description supplies everything an agent still needs: return shape is a status/message confirmation (not the allocated ID), the mechanism for getting real IDs, cross-tool handoffs (edit_geometry to assign, query_model to verify), and the no-backup warning. Nothing material is left 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 the per-branch field docs do the heavy lifting and a baseline 3 applies. The description nonetheless adds genuine meaning the schema does not: the selection rule for request.operation ('Choose request.operation by how the property is specified') and the namespace caveat that a thickness ID and a section ID are distinct even when their integers coincide.

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

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

The opening sentence gives a precise verb+resource ('Create or modify the shared material, section and thickness definitions used by structural elements') and immediately distinguishes the tool from named siblings (edit_geometry for assignment, edit_prestress for tendons, query_model for reads). An agent can tell what this tool owns without opening the 17-branch oneOf 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 routes the agent across every operation branch (create_material vs add_time_parameter vs the five section-creation variants, add_thickness vs frame sections) and states explicit exclusions, e.g. 'Do not use the latter [calculate_section_property] as a readback of a manual override' and 'remove_section deletes an explicit selection, while remove_unused_sections lets the bridge identify unreferenced definitions.' When-not conditions and alternatives are both present.

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 destructive=true and non-idempotent, and the description adds real behavioral context beyond them: full-definition updates reset omitted scalar fields, system switching clears definitions only with explicit clear_existing=true, writes refresh the model without running analysis, API availability depends on the desktop build, and actual IDs must be read back before activation. Units are also flagged as standard-specific rather than blanket-convertible.

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, then routing, then caveats, so the important content comes first. It is long but justified by a 14-branch tool; the main waste is the duplicated Chinese parenthetical restating each English clause and a slightly list-like middle paragraph.

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

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

An output schema exists so return values need not be explained, and the description covers the cross-cutting concerns an umbrella tool must: system selection prerequisite, per-standard units, definition-replacement semantics, clear_existing behavior, and the define-then-stage-then-solve workflow. Per-operation detail is correctly delegated to the nested schemas, though the breadth of 14 operations means the top-level text cannot address each one.

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% and the single 'request' parameter is a discriminated union whose branch schemas already document every field, so the baseline is 3. The description's note that 'request.operation selects the family's exact schema' and that typed requests 'stay nested' largely restates the discriminator already declared in the schema.

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

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

States a specific verb and resource ('Configure the live-load system and define moving, transversal or international vehicles, lanes and cases'), then enumerates the operation families it owns (node tandem, influence plane, lane, vehicle, cases) so an agent can tell it apart from edit_loads, query_model and edit_construction 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 routing is provided both inside the tool ('set_transversal_vehicle/lane/case define the transverse family'; 'remove_transversal_data removes an explicit transverse target') and to siblings with conditions ('Use edit_loads for static loads, query_model for saved definitions, edit_construction to include cases in the operation stage and query_results for solved envelopes'). 'Select the matching system explicitly' states the prerequisite for the whole tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context: diagnostics return an unavailable connection as data, a successful call does not mean the bridge is connected or editable, the state can change between check and command, and operations take no arguments. These are non-obvious traits an agent could otherwise misread.

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 starting operation, then routing, then behavioral caveats. It is dense and somewhat long for a 1-parameter tool, and the bilingual parenthetical duplicates add length, but every sentence carries operative 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?

Although an output schema exists (so return fields need not be enumerated), the description still explains return semantics (structured state, suggested next actions, unavailable connection as data) and tells the agent to read connected/status and capability fields. Nothing needed 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 100% and the request schema documents the operation discriminator and each branch. The description adds one useful clarification beyond the schema – 'Supply request.operation only; these diagnostic operations have no arguments' – which preempts an agent over-filling the nested request.

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 (diagnose) and resource (QiaoTong connection, active model state, edit readiness) and immediately contrasts itself with engineering operations. The description also names the three sub-operations, so an agent can distinguish inspect_bridge from edit_* / query_* 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 when-to-use ('before choosing an engineering operation', 'start with check_qiaotong_connection') and explicit when-not ('these are diagnostics, not requests to open a model, clear results, prepare edits or switch stages'). It routes to named alternatives: query_model for engineering records and manage_model_files to open/save a project.

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 declare destructive/not-read-only/non-idempotent. The description goes well beyond: native-unit vs meters conventions with internal conversions, that a context read is not a lossless snapshot, that full replacements require carrying forward retained values, that empty assignment lists clear data, that verification timeout does not cancel background computation, that completion ≠ passing, and to save before destructive updates. This is exactly the behavioral 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-loaded with purpose and capped by a dense but organized behavioral paragraph; for a 17-operation mega-tool the length is largely earned. It is slightly packed (units, replacement, timeout, and completion caveats run together), but no sentence is pure filler.

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

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

Given an output schema exists and each sub-operation carries its own rich description, the top-level text needn't restate returns. It covers the two families, unit conventions, replacement hazards, and timeout semantics well, though it does not mention every branch (e.g. update_vertical_steel_tendon, add/remove_section_reinforcement, manage_check_material), leaving the reader to the schema for those.

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 and the heavy per-field semantics already live in the schema. The description still adds cross-cutting parameter meaning — 'request.operation selects the namespace, units and replacement behavior' plus the native-unit vs meters rule — which is genuine value over the schema's per-branch defaults.

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

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

The opening sentence names a specific verb set and resource ('Set up, edit, execute and inspect code-checking data') and immediately frames the two sub-families (model snapshots vs current concrete-checking context). It then enumerates key operations (setup_concrete_check, run_concrete_check, get_check_data, manage_check_case_file) and explicitly names the siblings edit_properties and analyze_model as different concerns. An agent can route correctly 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 both a workflow chain (setup_concrete_check imports → configure → run_concrete_check → get_check_data) and explicit alternatives ('Use edit_properties for structural materials/sections and analyze_model for the structural solve'). It even states when-not: this is concrete code checking, not the general structural solve.

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, but the description goes well beyond them: paths are interpreted by the QiaoTong host (possibly a remote Windows machine) rather than the MCP client, initialize_model requires confirm=true, open can discard unsaved work, save can overwrite, and there is no automatic backup or rollback. It also warns to verify the active model and discloses the return shape (a completion message, not model contents).

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 purpose, then routing, then behavioral caveats in a logical order. It is longer than one operation would justify, but the length is earned by three distinct destructive-ish sub-operations. The closing 'save important work first, verify after' mildly repeats the earlier unsaved-work warning, keeping it just short of 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 polymorphic, destructive file tool this covers everything an agent needs: operation routing, host path semantics, the confirm gate, overwrite/discard risk, absence of backup, and post-call verification. Returns are summarized and an output schema exists, so no further return-value detail is required.

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, but the description adds a genuine cross-cutting clarification: request.operation selects the matching branch fields, and file paths are resolved on the host rather than the client's local filesystem. That host-vs-client distinction materially changes how an agent should populate file_path, though the per-field detail still lives in the schema.

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

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

States specific verbs and a resource ('Open, save or initialize the active bridge project') and enumerates the three operations it multiplexes. It actively distinguishes itself from siblings by naming edit_geometry and manage_checks as the tools for entity edits and separate check files, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use routing per operation ('save_model_file to persist current work, open_model_file to replace the active project, initialize_model to clear it for a new model') plus named alternatives for adjacent concerns and a precondition ('Inspect connection/readiness first'). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, and the description still adds real behavioral content: calls neither solve nor make the model editable, generic getters slice locally while native queries page on the bridge, selectors must be preserved between pages, and 'empty data is not proof of a missing entity when a filter or unavailable backend is involved.' It stops short of covering failure modes or auth requirements in depth.

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, then operations, then alternatives, then routing mechanics — a logical progression. It is long and dense, but the length is justified by ten discriminated branches; a few clauses (e.g., the bilingual parenthetical) are redundant but 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 ten-branch dispatcher with rich nested schemas and an output schema, the description supplies the routing model, sibling disambiguation, and empty-result/pagination caveats, so the agent needn't be told about return values. Coverage is strong; per-branch units and edge constraints are left to the nested schemas, which is appropriate.

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 100% schema coverage and only one top-level parameter (request), the baseline is 3; the description earns extra by explaining the dispatch contract: 'request.operation selects one schema branch' and that query_model_data's typed request remains nested, with a concrete example. It clarifies that IDs/names refer to the current model.

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

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

The opening sentence states a specific verb+resource+constraint ('Read saved model definitions, locate entities or inspect model geometry without changing it'), then enumerates each of the ten operation branches (get_model_info, get_model_data, query_model_data, find_entities, list_group_members, tendon/transversal/international getters, calc_section_property, validate_model) with what each does. An agent can identify this tool's scope 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?

It explicitly routes the agent away to alternatives by condition: 'Use inspect_bridge for connection and permission diagnostics, query_results for solved responses, and manage_checks for the current concrete-checking context.' It also sub-differentiates within the tool, noting validate_model checks connectivity/definition consistency 'not structural adequacy' and that calc_section_property evaluates candidate geometry without storing 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 readOnly/idempotent/non-destructive, yet the description adds real behavioral context: 'These calls do not solve, refresh or certify result freshness', an empty response may mean an absent case or inactive tendon rather than zero, paged operations slice locally after backend retrieval with a next-offset hint, and 'Envelopes do not represent simultaneous loads'.

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 organized into scannable bullets plus a concrete example request, which is appropriate for a six-branch dispatcher. It is long and repeats some per-branch details already in the schema descriptions, so a little of the text does not earn its place beyond structured fields.

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 six-way discriminated union and an existing output schema, the description covers preconditions, empty-result interpretation, pagination behavior and sibling routing adequately. Minor gaps remain around unit conventions and per-operation availability nuances, which live only in the branch schemas.

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, but the description adds cross-cutting parameter meaning: stage_id=-1/0/positive semantics, the ID namespace rule (node vs element by result_type) and the concrete worked example request. It also warns that full case identifiers must come from QiaoTong results/UI rather than derived from combination codes, which is operational guidance beyond field-level docs.

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 ('Retrieve numerical structural responses from the bridge's result data') and then enumerates the six operation families with what each returns (analysis results, special/modal results, live-load envelopes, tendon loss/position/length). It explicitly distinguishes itself from siblings ('Use query_model for saved definitions, manage_checks for code-check results and view_model for plots'), so an agent can route without opening each 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?

States the precondition ('Use after analyze_model has completed the relevant solve') and gives per-branch selection rules, e.g. get_live_load_results 'request one maximum or minimum envelope extreme' and tendon geometry available pre-solve 'depends on the bridge'. Altern</br>atives are named with the condition that selects them (query_model/manage_checks/view_model), which is exactly when-to-use 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 only say readOnlyHint=false, destructiveHint=true, openWorldHint=false, idempotentHint=false; the description goes well beyond them. It discloses that the two image operations write PNG bytes to file_path on the MCP host and OVERWRITE that path (justifying the destructive hint), that return_image=false yields a saved-path message, that a failed preset still captures the current view and returns a warning instead of image content, that no solve runs and no prior view is restored, and that defaults are assignments rather than toggles.

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 two core capabilities, then organized into an operation-routing block and a cross-cutting constraints block, which is appropriate for a ten-branch discriminator schema. However, it is dense and repeats some branch-level schema facts (set_unit defaults, display_ids omission behavior, screenshot overwrite), so a little trimming would help.

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

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

No output schema exists, and the description compensates by explaining return shapes: confirmations for display operations, inline MCP Image content versus a saved-path message, and the text warning when a preset fails. Combined with write-path/overwrite behavior, authentication/connection requirements, and the no-solve/no-restore caveats, an agent has everything needed to call this 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 and the per-operation field docs already do the heavy lifting. The description adds cross-cutting semantics not obvious from any single branch: defaults are assignments not toggles, display_ids applies BOTH flags and an omitted flag hides that label family, set_unit sends both units every time, and view_angle='current' preserves the camera. These are useful, but several restate what the nested $defs already say, so it does not fully clear the bar for a 5.

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

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

Opens with a specific verb+resource+scope: control the desktop view and capture PNG images of the model or existing analysis results. It then enumerates all ten operations with a one-line role for each (camera/shading/labels/visibility, stage selection, screenshot, result plotting, units), so an agent can tell what the tool covers without reading the schema. It also names siblings it is NOT (query_results for numerical values, edit_geometry/edit_construction for entity/schedule edits).

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

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

Explicit routing guidance: 'Use query_results for numerical values' versus plot_analysis_result for contours, and 'edit_geometry and edit_construction change entities and schedules' versus display-only operations. Prerequisites are stated (a connected desktop view is required) and the when-to-use split between save_model_screenshot and plot_analysis_result is clear. Nothing is left to inference.

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