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

Annotations declare destructiveHint=true, and the description does not contradict it. The description adds meaningful behavioral context beyond annotations, such as 'solve applies mates in order and returns world transforms' and 'explode uses radial offsets by tree depth'. However, it does not explicitly warn about destructive or irreversible aspects of remove_part, leaving that to the schema.

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

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

The description is well-structured with a bulleted action list and a clear 'When not to use' section. Each line is concise and informative, with no filler. The length is appropriate for a multi-action tool and the most important information is front-loaded.

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

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

The description covers all eight actions, gives usage guidance, and clarifies the tool's role relative to siblings. The rich schema and output schema cover parameter details and return values. The description is fully adequate for an agent to select and invoke this 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?

Schema coverage is 100%, so baseline is 3, but the description adds value by explaining the purpose of key actions and their parameters (e.g., 'bom format json or csv', 'explode direction x/y/z'). It complements rather than repeats the schema, so a 4 is warranted.

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 'Create, edit, solve or analyze an assembly' – a specific verb+resource statement. It then enumerates each action (create/add_part/solve/etc.), and differentiates from sibling tools by stating it composes parts rather than geometry. This clearly establishes the tool's scope and unique purpose.

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?

An explicit 'When not to use' section tells the agent to use cad_object for geometry creation first and cad_drawing for drawings. The action list also implies the intended workflow (create assembly → add parts/mates → solve). This is exemplary usage 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?

The description adds substantial behavioral context beyond the annotations: execute is synchronous, scheduled jobs are 'durable across restarts', run_script is 'sandboxed', and stop_on_error halts on first failure. It also explains that schedule supports cron/dependency-chained jobs. This complements the destructiveHint annotation without contradicting it.

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 well-structured with bullets, a clear action list, and a dedicated 'When not to use' section. Despite covering seven actions, it remains scannable and every sentence adds relevant information without fluff. The bilingual text is a minor stylistic note but does not hurt clarity.

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 (seven actions, scheduling, templating, scripts), the description covers all key aspects: action semantics, synchronous vs scheduled execution, durability, sandboxing, and guidance for alternatives. With an output schema available, returning to documentation is unnecessary. The description is sufficiently complete for safe and 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?

The input schema has 100% coverage and a well-defined discriminated union, so the baseline is 3. The description adds value by clarifying the semantics of each action (e.g., execute runs tool+argument pairs, run_script is sandboxed, schedule supports cron/dependencies). It helps the agent understand how to choose the 'batch' union variant, which exceeds schema-only information.

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 the tool's purpose with a specific verb set ('Execute, schedule, inspect or manage batch jobs') and then enumerates each action (execute, schedule, status, cancel, list, templates, run_script). It distinguishes itself from sibling CAD tools by explicitly noting that it sequences other tools, making the purpose unambiguous.

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

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

The description provides explicit usage guidance including a 'When not to use' section: 'For a single operation call the concrete aggregate directly (cad_object, cad_file, ...)' and distinguishes synchronous execute from scheduled long-running work. This directly tells the agent when to prefer alternatives and when to use this tool.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description adds value by describing what each action actually produces: counts, toolpath length, bounding box for toolpath; length plus estimated machining time for simulate; and concrete G-code details (G0/G1, drilling cycles, M2 termination) for export_gcode. It goes beyond annotations but does not disclose error conditions or file overwrite semantics for the export action.

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?

An efficient bilingual layout: front-loaded English headline, a systematic triplet of bullets, and a trailing exclusion clause. Every bullet earns its place with concrete output details. The moderate redundancy between the headline and the bullets is minor, and the bilingual duplication of intent actually broadens accessibility without bloat.

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?

This dispatched tool has three distinct parameter modes, and the description covers all three thoroughly. Its geometry basis for each action is explained, and the output schema exists to document return values. Remaining gaps are minor: it doesn't explicitly state that a document must be open with valid contour/circle entities, nor how export_gcode handles existing files. For a compound tool of this complexity, these are acceptable omissions.

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 input schema has full description coverage, with each parameter already carrying types, defaults, and unit-level descriptions (mm/min, RPM, retract height). The tool description adds no parameter-level semantics beyond what the schema provides; it only contextualizes the geometry inputs (rectangles/polygons/circles), which is behavioral rather than parameter-specific. The baseline 3 is therefore 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 opening sentence names a specific verb+resource combination — generate, simulate, or export 2.5-axis toolpaths (contour + drilling) — so the agent knows exactly what kind of CAM operation this is. The three action bullets add further precision, and the 'When not to use' clause explicitly announces the tool is out of scope for full 3D toolpaths, distinguishing it from related siblings like cad_sim.

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 contains an explicit 'When not to use' section stating that full 3D toolpaths and tool-axis control are out of scope, which gives the agent a clear exclusion rule. The positive usage conditions are conveyed through the action list ('current document geometry'), but no sibling tool is named as the alternative for the 3D case, leaving the routing slightly less explicit than ideal.

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 (readOnlyHint=false, destructiveHint=false), the description adds meaningful behavioral context: it is a dispatch tool keyed by `tool`, sync is the WebSocket entry point, RBAC defaults to session owner for unknown users, and branch operations use CRDT. These details help the agent anticipate side effects and authentication/reliability nuances.

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 well-structured with a summary line, a bullet list per subdomain, and a when-not-to-use section. It is slightly verbose due to repetition between the first line and the Chinese summary, but the organization makes the information easily scannable for a complex dispatcher 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?

Given the tool's complexity (8 subdomains) and the existence of an output schema, the description is complete: it covers all subdomains, explains the dispatch mechanism, gives usage boundaries, and notes default identity behavior. No major selection or invocation criteria are 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?

The input schema already covers all parameters with descriptions, so the baseline is 3. The description adds value by mapping the `tool` discriminator to concrete subdomains and summarizing the actions each subdomain supports, which helps the agent choose the correct `collab` variant. It does not delve into parameter syntax because the schema already handles that.

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 identifies cad_collab as a multi-user collaboration dispatcher with a specific resource scope (sessions, branches, annotations, presence, history, resolve, permissions, sync). It lists concrete sub-operations for each subdomain and explicitly distinguishes itself from single-user sibling tools, making its purpose highly specific.

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 provides an explicit 'When not to use' section that tells the agent to use cad_object/cad_layer/cad_file for single-user edits, and it explains the identity/RBAC default behavior. Within the dispatcher, each subdomain's action list acts as a clear guide for when to use which branch of the 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description adds useful behavioral context: 'solve runs the constraint solver and reports residual error' and mentions the optional 'planegcs' backend. This goes beyond the annotations by clarifying solve behavior and backend dependency. No contradiction with 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 compact and front-loaded: first sentence states the full purpose, the middle elaborates on solve behavior, and the final section gives exclusions. Every sentence earns its place; no fluff.

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 has a discriminated union with four actions, the description covers all of them, explains when not to use it, mentions the solve backend, and the output schema exists so return values need no explanation. It is complete for the tool's 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 description coverage is 100%, so the schema already documents parameters well. The description adds extra semantic value by giving constraint type examples (coincidence, distance, angle) and explaining that solve reports residual error, which is not in the schema. This lifts it above the baseline of 3.

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+resource: 'Add, remove, list or solve geometric constraints.' It clearly enumerates all four actions and gives concrete constraint examples (coincidence, distance, angle), distinguishing it from sibling tools like cad_assembly and cad_object by explicitly scoping to geometry.

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 provides explicit 'When not to use' guidance, naming cad_assembly for assembly mating (action=add_mate/solve) and cad_object for direct transforms (action=transform). This directly answers when to use the tool versus alternatives.

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

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

Annotations already declare destructiveHint=true, and the description consistently lists 'delete' as an action, adding context about confirm-driven deletion via schema but not restating it. The description adds behavioral details beyond annotations: the action dispatch mechanism, supported export formats (svg/dxf/pdf), view types, dimension standards, and GD&T symbols. It does not contradict 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 well-structured: a one-line summary, a brief Chinese coordinating phrase, bulleted action semantics, and an explicit not-to-use section. Every sentence contributes, and the bullet format makes the multi-action behavior scannable. It is appropriately sized for a tool with seven distinct operations.

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 (7 actions), the description covers every action with relevant detail, states output formats, and provides sibling-tool exclusions. The output schema exists, so return values need not be explained in the description. The only minor omission is not explicitly warning about the delete confirmation, but the schema's 'confirm' parameter covers that, and the destructive hint annotation already flags it.

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

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

Schema description coverage is 100%, so the heavy lifting is done by the schema. However, the description adds semantic meaning beyond raw parameter names: ISO 129-1 for dimensions, GD&T feature-control frames, paper sizes A0-A4, and the mapping of actions to their purposes. This enriches the agent's understanding of how parameters combine, though it doesn't define every property 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 opens with a specific verb+resource: 'Create, edit or export an engineering drawing.' It then enumerates all dispatched actions (create, add_view, add_section, add_dimension, add_tolerance, delete, export) with concrete definitions, and clearly distinguishes itself from sibling tools in the 'When not to use' section. This is far beyond a vague or tautological purpose.

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

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

The description explicitly provides a 'When not to use' section naming cad_render for preview images, cad_file for interop files, and cad_object for geometry edits. It also implicitly maps each action to its intended drawing scenario, such as ISO 129-1 dimensions and GD&T frames. This gives clear decision guidance for agent tool selection.

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 provide no hints (readOnly, idempotent, destructive all false), so the description carries the transparency burden. It discloses OCCT backends with fallbacks, exactness on OCCT kernel, `requires_occ` reports, and rigid transform patterns. It does not specify side effects on source entities, but the 'creates new geometry' phrase implies non-destructive behavior, which is useful.

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 well-structured: summary, Chinese translation, action-specific bullets, and a 'When not to use' section. It is front-loaded and avoids fluff, though the bilingual repetition is slightly redundant. Overall, every sentence 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?

Given the tool's complexity with seven distinct actions, the description covers each action's behavior, kernel dependencies, fallbacks, and usage boundaries. The output schema also exists, so return-value details are not needed. The description is complete enough for correct tool selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by mapping actions to the key parameters (`path`, `profile_ids`, `entity_id`, `radius`, etc.) and clarifying semantics like 'rigid transforms' and 'available on every kernel.' It does not duplicate schema text but provides high-level behavioral meaning per action.

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 clear summary, 'Sweep, loft, fillet, chamfer or pattern geometry,' listing all supported actions. It further distinguishes from sibling tools via the 'When not to use' section, naming cad_object for parameter edits and boolean operations. This fully satisfies purpose clarity.

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 includes an explicit 'When not to use' section that names alternative tools and usage contexts, such as cad_object for update/transform and boolean. It also clarifies kernel-dependent behavior for each action group, giving the agent clear guidance on when each action is appropriate.

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 set destructiveHint=true, and the description aligns by listing 'delete' and 'save' actions. It adds context beyond annotations: open/save use JSON scene format, create accepts template/unit, export/import handle interop formats. No contradiction found.

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?

Description is well-structured and front-loaded: starts with a one-line summary, then action details, then exclusions. Every sentence adds value; no redundancy or fluff.

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

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

The description covers all 8 actions, dispatch model, file formats, and sibling differentiation. Since an output schema exists, return-value details are not required. The description is complete for a complex multi-action tool.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds meaningful semantics by summarizing action behavior (e.g., export writes to interop formats, import loads .json/.dxf/.step/.dwg), which complements the schema. It mentions .dwg import not explicitly in the schema's import path 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 clearly states the tool's scope: 'Create, open, save, close, delete, list, import or export files.' It uses a specific verb list and explicitly differentiates from siblings by saying 'For per-object geometry edits use cad_object; to import/export raw JSON scene data (not files) use cad_json'.

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 includes a 'When not to use' section that names concrete alternative tools (cad_object, cad_json), and gives format guidance (e.g., 'step (recommended)'). This is explicit guidance on when to use and when to avoid.

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 provide idempotentHint=true and destructiveHint=false, but the description adds non-obvious behavior beyond those: export maps color attributes to PBR baseColorFactor, import creates mesh entities, and preview returns a lightweight mesh-count/bbox summary. That is useful context an agent would otherwise not know.

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 compact and front-loaded: a one-sentence summary, then three bullets for the dispatch branches, then a routing note. There is a little redundancy between the initial English sentence and the bullets, but it is minor and the structure is easy to parse.

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 tool with three discriminated action variants, an existing output schema, and annotated safety properties, the description is complete. It covers each action's semantics, highlights color and entity mapping implications, and specifies the alternative to use for non-glTF engineering formats.

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 adds real semantic value by explaining that the union object is dispatched by 'action' and by describing what each action does with the relevant state (current document, target or source file, mesh entities). It does not repeat field names verbatim, rather gives operational context beyond the schema.

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

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

The opening sentence states a clear verb and resource: 'Export, import or preview glTF 2.0 geometry.' The bullet list expands each action with enough detail to distinguish export, import, and preview, and the 'When not to use' note names the sibling tool (cad_file) it is not. A model 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?

The description explicitly states the tool's intended scope (dedicated to glTF mesh assets) and contains a 'When not to use' section directing agents to cad_file for engineering formats like STEP/DXF/STL. It also specifies that the tool dispatches by action, so the appropriate usage for each branch is fairly 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 description contradicts the annotations: readOnlyHint=true conflicts with actions such as save (writes to file) and import_geometry/import_scene (modify or create documents). The description itself reveals these mutating behaviors, yet the annotations claim read-only. This is a severe inconsistency.

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 structured with a clear summary, a bulleted action list, and an exclusion paragraph. It is somewhat lengthy due to bilingual duplication, but every section earns its place and important information is front-loaded.

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

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

The description covers all 8 actions, explains the in-memory scope, and provides usage exclusions, which is strong for a multi-action tool. The presence of an output schema reduces the need to explain return values. One point is lost due to the annotation contradiction that undermines overall clarity.

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 fully documents every parameter. The description adds a high-level list of actions and bilingual explanations, but does not go beyond the schema to clarify parameter syntax or edge cases. 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 clearly states specific verbs and resources: 'Read / parse / validate / import / export JSON' and enumerates 8 distinct actions. It distinguishes from siblings by explicitly framing cad_json as operating on JSON text and in-memory scene data, unlike cad_file or cad_object.

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 includes an explicit 'When not to use' section that names cad_file for file-level open/save and import/export, and cad_object for geometry editing. This gives clear guidance on when to choose this tool vs alternatives.

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

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

Annotations already declare destructiveHint=true, so the description adds value by specifying that 'delete removes the layer *and* the objects on it'—a critical side effect. It also explains the layer concept (grouping objects for display/selection) and that update can toggle visibility/locked, going beyond the generic destructive flag.

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 purpose and well-structured, ending with explicit alternatives. The Chinese sentence duplicates the English dispatch explanation, adding minor redundancy, but the overall length is appropriate and every sentence contributes useful context.

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

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

With a rich union schema and an output schema present, the description covers the CRUD operations, critical destructive behavior, and alternatives. It lacks details on error conditions or return formats, but those are not required given the output schema and the tool's straightforward nature.

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 summarizes what each action accepts (e.g., create accepts color/linetype/linewidth; update can toggle visible/locked), but these details are already present in the schema's property descriptions. It does not add new format or syntax information beyond the schema.

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

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

The description opens with 'Create, read, update, delete or list layers,' a specific verb+resource combination. It further distinguishes from siblings by explicitly naming cad_object and cad_status as alternatives for different use cases, making the tool's scope unmistakable.

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 'When not to use' section gives explicit alternatives: per-object layer membership via cad_object, per-layer object counts via cad_status, and hiding objects via cad_layer (update visible=false). This provides clear decision guidance for when to use this tool versus siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context beyond this: it notes the tool 'reads existing geometry', details that area action returns area for 2D kinds and volume for 3D kinds, and explains output includes a 'kind' field. This enhances understanding of the tool's behavior without contradicting 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 well-structured and front-loaded with a clear summary. Each section (action details, output semantics, alternatives) earns its place without unnecessary verbosity. The use of bullet points and 'When not to use' enhances readability and scannability.

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

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

Given the tool's moderate complexity, the description covers all essential aspects: the two actions, parameter requirements, output behavior, and exclusions. Since an output schema exists, return values are documented elsewhere. The description is complete for an agent to select and 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?

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining how the 'action' parameter discriminates between the two measurement modes, the point format for distance, and the object_id usage for area/volume. It also clarifies the output units (mm^2, mm^3), which is not fully explicit 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?

The description clearly states the tool measures distance or an object's area/volume, with specific actions (distance/area) and differentiates from sibling tools like cad_object and cad_validate by specifying what it does not do. The verb 'measure' and resource (geometry) are explicit.

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 provides explicit usage guidance, including a 'When not to use' section that names alternatives (cad_object, cad_status, cad_validate) for other queries. It also explains the action-based dispatch for distance vs area/volume, giving clear context for when each mode is appropriate.

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 provide no safety hints (all false), so the description carries the full burden. It discloses critical behaviors: command does NOT execute the tool call, ambiguous requests return suggestions, and chat creates objects immediately and remembers them for anaphora resolution. This goes well beyond the annotations and fully informs the agent of side effects and return semantics.

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 well-structured with bullets and front-loaded with the main purpose. However, the Chinese sentence '聚合 NLP 操作。按 ``action`` 派发：command / chat。' essentially repeats the opening English sentence, adding mild redundancy. Otherwise, every sentence 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?

Given the tool's complexity (two modes, anaphora, parsing vs execution), the description covers all key aspects: when to use, what each mode does, return behavior, and exclusions. With an output schema present, no return format details are needed. The description is complete for an agent to select and 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?

Although schema coverage is 100%, the description adds essential semantics: it explains the action discriminator's meaning, what command returns (tool + arguments, no execution), and how chat handles anaphora. This is practical, actionable information that the schema's property descriptions do not provide, significantly enhancing 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 description clearly states a specific verb+resource: 'Parse a natural language request into a tool call or continue a chat.' It further distinguishes between command and chat modes, and positions the tool as a convenience dispatcher relative to concrete sibling tools like cad_object and cad_file. This makes its purpose unambiguous.

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

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

The description provides explicit when-not-to-use guidance: 'For deterministic, schema-driven control prefer calling the concrete aggregate tools directly (cad_object, cad_file, ...).' It also clarifies that command only parses and requires the agent to dispatch the returned call, giving clear direction on when to use this tool versus alternatives.

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

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

Annotations already indicate destructiveHint=true, and the description adds that cad_object 'edits the current document's geometry,' making the mutation scope explicit. It also discloses that the boolean action 'requires the optional boolean extra,' which is essential operational context beyond the schema. No contradiction with annotations exists.

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 structured with a lead summary, bullet-like action breakdown, and a dedicated 'When not to use' section. Despite being longer than average, every sentence serves a purpose and the layout is scannable for an agent needing to dispatch by action. No fluff or repetition beyond the minor bilingual restatement.

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

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

The tool has 8 distinct action variants and an aggregate schema, yet the description covers each action's purpose, key parameters, and return behavior for create. It also addresses optional prerequisites (boolean extra) and sibling tool boundaries, making it fully adequate for selection and invocation even with the output schema present.

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?

Though schema description coverage is 100%, the description adds critical semantic detail: it lists the allowed create types (line, circle, arc, etc.), specifies that transform uses a '4x4 matrix (column-major, translation in the fourth column)', and notes that create returns 'the new object_id and bounding box'. These enrich the bare schema parameter descriptions.

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

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

The description opens with 'Create, read, update, delete, copy, transform, list or boolean objects,' a specific verb+resource statement that also enumerates the distinct actions. Each action is further elaborated with its target (e.g., 'add an entity by type', 'apply a 4x4 matrix'), and the tool is explicitly differentiated from siblings like cad_file, cad_json, cad_measure, and cad_validate.

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

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

A 'When not to use' section explicitly names alternative tools (cad_file for import/export, cad_json for JSON round-trips, cad_measure for measurements, cad_validate for validation) and clarifies that cad_object edits the current document's geometry. This gives the agent both positive and negative usage signals.

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 discloses critical security behavior: plugins run in the same process/trust domain without process-level sandboxing, install only loads entry-point plugins from installed distributions and rejects arbitrary module:attr imports. This meaningfully exceeds annotation context and helps agents judge risks; minor details like persistence of enable/disable state are not covered, but the key trust-boundary behavior is 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 list is front-loaded, and the structure flows logically: overview, dispatch details, security, then when-not-to-use. It is a bit longer than strictly necessary due to bilingual repetition, but each section serves a distinct guidance purpose and is not bloated.

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 dispatcher tool with six actions, the description covers every action's semantics, the dangerous install edge case, the unresolved security hardening item, and usage boundaries. Since output schemas exist for each action variant, no return-format explanation is necessary; everything an agent needs to call it correctly is present.

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 schema already documents all parameters. The description adds useful conceptual framing about install semantics and the trust boundary of module paths, but it doesn't provide additional format-level detail beyond the schema, so the 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 clearly states the verb and resource: install, uninstall, list, enable, disable or inspect plugins. The opening sentence names every supported action, and the final line explicitly scopes the tool to plugin lifecycle management, distinguishing it from sibling tools that expose plugin capabilities.

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 provides a 'When not to use' note stating that actual plugin capabilities should be invoked via their registered MCP tools, not through cad_plugin. This gives the agent clear selection guidance and alternative routing, well beyond simple implied usage.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds valuable context that it 'produces images / sync deltas only' and details output formats per mode, reinforcing the non-mutating behavior. It does not contradict annotations and provides useful output-format 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 front-loaded with a one-line summary, followed by a concise mode list and a well-structured 'When not to use' section. The bilingual list adds a bit of redundancy but remains compact and every line carries informational value.

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 six discriminated modes, the description covers all relevant scenarios: what it does, which modes exist, what output each produces, and clearly explains when to use sibling tools instead. The output schema is present, so return-value details are already handled, making the description adequate for safe tool selection.

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 each parameter has its own description. The description adds a mode-to-output-format mapping (e.g., ortho -> PNG, animation -> GIF, webgl -> delta) that the schema does not capture, helping the agent understand the semantic difference between modes beyond their 'const' values.

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 the tool renders the document in a selected mode and enumerates six modes with their output types (PNG, GIF, sync delta). It distinguishes itself from sibling tools by explicitly naming cad_view, cad_drawing, and cad_file as alternatives for other operations.

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 explicit 'When not to use' guidance with direct references to cad_view (storing/editing view definitions), cad_drawing (SVG/DXF/PDF exports), and cad_file (interop geometry files). This clearly directs the agent to the right tool for adjacent 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 already indicate destructive behavior (destructiveHint=true) and non-read-only. The description adds valuable context: mesh is 'pure Python, always available', FEA/kinematics backends are optional and absent engines report 'requires_sim', and run can schedule an async batch job. This goes beyond annotations without contradicting them.

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

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

The description is tightly packed with useful information: action list, backend constraints, and alternatives. It uses structure (bullets and bold) to aid scanning without redundancy. Every sentence contributes to selection or invocation.

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 (multiple action variants, optional backends, async scheduling) and the presence of an output schema, the description covers all operational aspects: setup, run, mesh, result, list, delete, and when not to use it. No critical gaps identified.

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 per-action descriptions for all fields. The description adds semantics by explaining the discriminated union (`action` dispatch) and clarifying backend requirements and always-available mesh. This enriches parameter understanding 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?

Description opens with a specific verb+resource: 'Mesh, setup, run, inspect or delete a simulation.' It enumerates all actions and explicitly distinguishes from siblings by directing alternative use cases to cad_validate and cad_object. This is clear and well-differentiated.

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 explicit when-to-use guidance with a dedicated 'When not to use' section naming cad_validate (geometry/interference) and cad_object (pure geometry meshing previews). Also explains backend optionality (CalculiX/PyBullet) and async vs sync execution, which helps choose appropriate actions.

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=false, idempotentHint=true, and destructiveHint=true, so the safety profile is known. The description adds context by explaining what each target returns (e.g., health includes server version/uptime/tool count) and explicitly notes that logs_clear clears the in-memory buffer, aligning with the destructive hint. It does not contradict annotations, though it does not elaborate on side effects beyond logs_clear or error behavior, so it is 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?

The description is well-structured with bullet points and a dedicated 'When not to use' paragraph, and the first sentence clearly summarizes the tool. The Chinese sentence repeats some of the English enumeration, adding slight redundancy, but overall the length is appropriate for the tool's complexity.

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

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

The tool is complex with seven target types, and the description covers all of them, explains their use cases, and provides alternatives. Since an output schema exists, the description does not need to detail return values. Minor gaps include not mentioning the default target (check) or error handling, but the schema covers defaults, so the description is sufficiently complete.

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

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

The input schema has 100% description coverage, with each property and target variant described in detail. The description restates the targets and their purpose but does not add new parameter-level semantics beyond what the schema already provides. Per the calibration guidelines, a baseline of 3 is appropriate when the schema carries the load.

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+resource: 'Query session, file, object, layer, health or logs status' and then enumerates each target with distinct semantics (check, file, object, layer, health, logs_get, logs_clear). It also differentiates from sibling tools by explicitly naming cad_validate and cad_measure as alternatives for other concerns, making the tool's purpose very clear.

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 explicit 'When not to use' guidance that names alternatives (cad_validate for validation/aggregate stats, cad_measure for measurements) and clarifies that cad_status is for live session/server state. It also explains when to use each target variant, giving the agent clear decision criteria.

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 read-only/idempotent/non-destructive behavior. The description adds per-action output semantics (e.g., issues with type/location/fix_suggestion, overlap volume, manifold status, aggregate metrics) which goes beyond annotations. Minor gap: doesn't mention error conditions or performance characteristics, but overall 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 description is well-structured with a one-line summary, detailed bullets per action, and a dedicated 'When not to use' section. Every part adds value; no redundant or filler content. The bilingual note is brief and harmless.

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 as a four-action dispatcher, the description covers each action's purpose, key inputs, and output highlights. Combined with rich schema descriptions, an output schema, and clear annotations, the description is complete for selecting and invoking 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?

Schema coverage is 100%, so the schema already documents the 'query' discriminator and 'object_ids' filter thoroughly. The description reinforces the action choices and mentions the optional object_ids filter, but doesn't add meaningful new parameter-level detail beyond what the schema provides. 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 clearly states the tool validates geometry, detects interference, inspects topology, or fetches metrics. It explicitly enumerates the four actions and distinguishes itself from siblings in the 'When not to use' section, naming cad_measure, cad_status, and cad_json as alternatives for other use cases.

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 explicit guidance on when to use this tool versus alternatives. The 'When not to use' section names specific sibling tools for simple measurements, live status, and JSON validation, making the decision boundary very 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 description adds meaningful context beyond the annotations, such as document-scoped scope, numeric-only values, expression referencing, and {name} interpolation. The annotations (readOnly=false, idempotent=false, destructive=false) are not contradicted, though the description could have noted that the 'list' action is read-only.

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 well-structured, with the main purpose upfront, a usage example, and a 'When not to use' section. The inclusion of Chinese text adds redundancy for an English-consuming agent, but each section contains useful information and the description remains appropriately sized.

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 (a discriminated union with set/list modes), the description covers all key aspects: setting with value/expr, list mode, interpolation, and explicit exclusions. The presence of an output schema means return values are already documented, so the description is complete for selecting and invoking the tool.

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

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

The input schema already provides 100% coverage with detailed descriptions for all fields. The tool description adds extra semantic value by explaining how value and expr can be combined, giving an example expression, and describing CLI interpolation with {name} tokens, which goes beyond the schema.

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

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

The description clearly states 'Set or list parametric variables in the current document', providing a specific verb and resource. It distinguishes this tool from siblings by focusing on document-scoped variable bookkeeping, which no other sibling tool covers.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it warns against storing free-form strings and explicitly names cad_object_update as the alternative for geometry changes. It also explains how to use value/expr and the {name} interpolation, giving concrete usage context.

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 indicate this is a mutating, non-idempotent, non-destructive operation. The description adds valuable context: snapshots are in-memory (not durable), diff uses deepdiff and reports changed/added/removed fields, and restore rolls back the document. This goes beyond the annotation flags, though it does not discuss all side effects or permission requirements.

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 well-structured: a one-line summary, a paragraph explaining each action, and a dedicated 'When not to use' section. However, it repeats the same content in Chinese ('按 action 执行版本快照操作'), which is redundant for an English-language tool description. Still, the structure is clear and information-dense.

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

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

The description covers all four actions, the in-memory nature, and the key differentiators from sibling tools. It also explains the diff output format (changed/added/removed fields). An output schema is present, so return values are likely documented elsewhere. Minor gap: it does not explicitly state the default action (list) or required parameters, but the schema covers those. Overall, this is complete for a multi-action tool.

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

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

Schema coverage is 100% with each parameter having a description in the $defs (e.g., label, author, file_id, version_a/b). The description only provides high-level action semantics ('labeled snapshot', 'diff compares two snapshots') without adding new parameter-level meaning. Baseline 3 is appropriate since 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 description opens with a specific verb and resource: 'Save, list, diff or restore document version snapshots.' This clearly distinguishes the tool's four actions and the resource (document version snapshots). It also names sibling tools (cad_file, cad_collab) in the 'When not to use' section, further differentiating purposes.

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

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

The description gives explicit guidance on when not to use this tool, naming alternatives: 'For durable file persistence use cad_file (save/export); for collaboration branches use cad_collab (tool=branch).' This is a clear usage distinction and helps the agent choose 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?

The annotations already signal destructive behavior (destructiveHint=true), and the description adds context about the scope (definitions only), uniqueness constraints (unique name per document), and an optional explicit view_id. However, it does not detail side effects like irreversibility of deletion or field-clearing behavior, though such details appear in the schema.

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

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

The description is concise, front-loaded with the primary CRUD purpose, followed by domain details and an explicit when-not-to-use guidance. The bilingual repeat is acceptable and doesn't add bloat.

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

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

Given the rich schema and annotations, the description adequately covers the tool's scope and constraints, including its distinction from rendering. It doesn't need to explain return values due to the output schema.

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

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

The schema has 100% parameter description coverage, so the schema already documents each field. The description adds minimal parameter-specific meaning beyond mentioning the action discriminator and the uniqueness of name, which are also covered in the schema. Baseline 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 clearly states the tool's function with specific verbs ('Create, read, list, update or delete') and identifies the resource ('3D view definition'). It also distinguishes from sibling cad_render by explicitly stating what not to use it for.

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

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

The description explicitly includes a 'When not to use' section, directing users to cad_render for rendering and clarifying that cad_view only manages definitions. This provides clear guidance on when to use this tool versus an alternative.

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