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

With no annotations, the description carries the full burden. It discloses that the bus argument is a substring of an existing bus name and that drops are populated via later tool calls, but it does not mention side effects, error behavior, or whether the drop is modified in place, created fresh, or subject to validation. The power-supply note is useful domain context, not tool behavior.

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

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

The text is compact and front-loaded with the core action, then delivers parameter details and workflow in a logical order. The parenthetical examples add clarity without bloat, though the sentence about part_number would benefit from similar treatment, making it slightly denser than necessary.

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 is adequate for a read of the intended workflow, but it leaves a required parameter unexplained and gives no information about output, validation, or potential failure modes. For a mutation tool in a complex hardware domain, this is a noticeable gap that an agent would have to probe at runtime.

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

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

The description explains 'bus' and 'drop' meaningfully, but it omits 'part_number', which is listed as a required argument yet is absent from the schema's properties list. Version is also not explained. With schema coverage effectively low (at least one required parameter undocumented), the description fails to compensate for the most critical gap.

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

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

The description opens with a specific verb and resource: 'Add a drop to a bus', then grounds it with a concrete example (remote X80 EIO drop on an M580 EIO/RIO bus). It also clarifies the bus/drop parameter semantics, which clearly distinguishes this tool from siblings like add_rack and add_io_module by stating the drop is the parent to be populated later.

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

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

Explicitly names the follow-up tools ('Then use add_rack and add_io_module to populate it') and provides a prerequisite ('bus is a substring of the bus name from get_hardware'). It also gives a domain caution about remote racks needing their own power supply, which helps the agent decide when and how to invoke the tool correctly.

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

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

There are no annotations, so the description carries the full behavioral disclosure burden. It does communicate that the tool mutates the project topology and implies the added DTM is initially unconfigured until IP and dataset calls are made. However, it does not disclose duplicate behavior, whether the parent must already exist, persistence implications, or error conditions. The behavioral context is adequate but incomplete.

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 every sentence earns its place: a clear one-line purpose, then two scenario definitions, then the necessary follow-up workflow. It is slightly longer than the minimal case but not redundant, 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?

For a six-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description is not complete enough. It covers the common top-level and slave workflows well, but it omits semantics for four parameters and gives no indication of the return value or error behavior. An agent would still have to guess about several inputs.

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

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

Schema description coverage is 0%, so the description must compensate. It explains parent_dtm and device_type_name well through concrete examples. But it leaves dtm_name, prog_id, version, and protocol_id completely unexplained, even though dtm_name is required. Four of six parameters remain underspecified, which is a significant gap for an agent trying to invoke the tool correctly.

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

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

The description opens with a clear verb and resource: 'Add a DTM to the project topology.' It also differentiates this from sibling hardware tools like add_io_module, add_drop, and add_rack by focusing specifically on DTM objects, and distinguishes top-level vs slave DTMs. An agent can tell what operation this performs and what object it operates on.

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

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

The description gives explicit usage guidance for the two main scenarios: leave parent_dtm empty for a top-level communication DTM, and set parent_dtm to the master's name for a slave device. It also names follow-up tools like set_dtm_address and get/set_dtm_dataset or set_dtm_control_parameters. It does not explicitly state when not to use this tool or compare it directly with alternatives, but the scenario-based guidance is strong.

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

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

With no annotations, the description carries the full disclosure burden. It reveals important behavioral constraints: part_number/version must match the catalog exactly, version may need adjustment ('try both'), and defaults for rack/drop/bus assume a local rack on the local bus. It also references get_hardware for topology, but omits side effects like whether an existing module gets overwritten or error behavior on invalid slots or part numbers.

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

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

The description is a tight, two-sentence paragraph that leads with the core purpose, then layers constraints and defaults. Every sentence adds value, with examples kept relevant and no filler. It's appropriately sized for the 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 description is fairly complete for a mutation tool: it covers purpose, constraints, defaults, and a hint for topology via get_hardware. Missing elements include what happens on failure (e.g., invalid part number, occupied slot) and whether the operation is reversible, which are important given no output schema and no annotations. These gaps keep it from being fully self-sufficient.

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

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

Schema description coverage is 0%, yet the description compensates fully by explaining every parameter: part_number with concrete examples, version with compatibility hints, slot as rack position (CPU at slot 0), and rack/drop/bus defaults and local-bus semantics. This adds substantial meaning beyond the bare schema fields.

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

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

The description uses the verb 'Add' with a specific resource ('hardware module') and target ('rack slot'), clearly distinguishing it from sibling tools like replace_io_module or remove_io_module. It also narrows the scope to IO/communication modules, making its purpose unambiguous without needing to inspect 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 explains when to use this tool (adding a module to a slot) and provides practical guidance like checking topology with get_hardware and defaults for rack/drop/bus. However, it does not explicitly contrast with alternatives such as replace_io_module or mention when not to use it, leaving some inference to the agent.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It indicates a creation action and adds platform constraints, but does not mention prerequisites, side effects, reversibility, or what happens if the network already exists. While the core behavior is clear, deeper behavioral aspects remain undisclosed.

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

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

The description is two crisp sentences with no filler. The core action and platform scoping are front-loaded, and the alternative guidance appears in the second sentence. Every word contributes to understanding the tool.

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

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

The description is too sparse for a tool with two parameters and no annotations. It lacks details on the meaning of 'name', acceptable values for 'family' (beyond the example), expected return or errors, and any relation to sibling tools like list_networks or set_network_ip. An agent cannot confidently call this tool correctly without additional context.

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 description coverage is 0%, so the description must explain both parameters. It provides an example for 'family' (Ethernet) but gives no explanation for 'name'. This partial compensation leaves the semantics of 'name' entirely unaddressed, which is insufficient for an agent to construct correct arguments.

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 starts with a clear verb and resource: 'Create a logical network'. It adds platform context (Premium/Quantum) and clarifies that on M340/M580 the user should configure elsewhere, distinguishing the tool's purpose from alternative actions. This is specific and actionable.

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 when to use this tool (Premium/Quantum platforms) and when not to (M340/M580, where communication should be configured on modules/DTMs). This provides concrete guidance on choosing between this tool and the alternative approach, though it doesn't name a specific sibling 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?

No annotations are provided, so the description must fully explain behavioral traits. It states that it adds a rack and mentions a procedural sequence, but it does not disclose side effects, reversibility, prerequisites (e.g., whether the drop must already exist), or error conditions. This is a significant gap for a hardware mutation tool.

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

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

The description is two sentences with no redundant wording. It front-loads the tool's purpose and packs procedural guidance into the second sentence. 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?

For a tool with 5 parameters, no annotations, and no output schema, the description covers the main purpose and gives a follow-up workflow, but it lacks explicit preconditions (e.g., an existing drop), parameter details for 'rack' and 'version', and information about return values or failure modes. It is adequate for basic use but incomplete for a fully informed agent.

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

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

The schema has 0% parameter descriptions, so the description must compensate. It clarifies that bus and drop are used to target the remote rack and gives an example part_number ('BME XBP 1200'). However, it does not explain the rack parameter or the version parameter, leaving some ambiguity. The description adds partial meaning but not complete coverage of all five parameters.

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

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

The description clearly states the action: 'Add a rack to a drop' with a concrete example ('BME XBP 1200' in a remote EIO drop). It distinguishes from related tools like add_io_module and add_drop by focusing on the rack-level operation and even references the follow-up workflow.

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

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

The description provides clear context for when to use this tool (adding a rack) and immediately instructs the agent on the next steps (add power supply/modules with add_io_module and set drop/bus accordingly). It implicitly differentiates from add_drop by focusing on racks within existing drops, though it does not explicitly state when NOT to use 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?

No annotations are provided, so the description carries the burden. It discloses important behavioral facts: it runs analysis without generating code and is faster than a build. It also implies a read-only validation behavior via 'validate edits'. However, it does not explicitly state side effects or return format, leaving minor uncertainty.

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

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

Two sentences that efficiently communicate the core function, a key constraint (no code generation), a comparative advantage (faster than build), and a concrete use case (validate edits). Every word earns its place with no 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 zero-parameter tool with no output schema or annotations, the description provides the essential information needed to call it correctly: what it does, when to use it, and how it differs from siblings. Missing details like return format are minor because the tool's simplicity and usage direction suffice.

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

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

The tool has zero parameters, so the baseline of 4 applies per the instructions. Schema description coverage is trivially 100% and there are no parameters to document, so the description need not address parameter details.

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 states a specific verb and resource: 'Run a syntax/semantic analysis of the project'. It explicitly says it does not generate code, which distinguishes it from build_project and other code-generation siblings. The 'Faster than a build' comparison further clarifies its role versus a build.

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

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

The description explicitly says 'use it to validate edits' and notes it is faster than a build, offering a clear condition for when to choose it. This gives an agent a direct reason to pick this tool over the alternative build_project, and even implies when not to use it (when code generation is needed).

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

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

With no annotations, the description carries the full burden and does so well. It discloses the incremental default, the rebuild_all override, the automatic fallback to a full rebuild when 'Build changes function not available' occurs, and that a 'note' is added when that fallback happens. This is substantial behavioral detail beyond the bare 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 compact and well-structured: the first sentence gives the core behavior and return values, the second states the transfer prerequisite, and the final paragraph explains the important edge case. Every sentence earns its place, and the key 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?

For a single-optional-boolean-parameter tool with no output schema, this description is complete. It covers the parameter semantics, the return values, the operational requirement, and a realistic error scenario with the tool's automatic response. An agent has everything it needs to call 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 0%, so the description must explain the rebuild_all parameter. It does: rebuild_all=True means full rebuild, default is incremental, and it explicitly reassures the agent that the flag is not needed on first build. This fully compensates for the lack of schema descriptions.

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

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

The description states a specific verb and resource: 'Build the project' with clear variants (incremental by default, full rebuild with rebuild_all=True). It also describes the return content (build state and Control Expert output text with errors/warnings), which helps differentiate it from the sibling build_remoteconnect_logic_copy.

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 context: a successful build is required before transferring to a PLC or simulator, and the default call is safe even on a fresh project. It does not name alternative tools or explicitly say when not to use it, but the stated prerequisite and auto-fallback behavior give clear operational 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?

With no annotations provided, the description carries the full burden of behavior disclosure, and it does so well. It reveals that the paired logic file is opened without saving in place, that output_path is not written on edit/build failure, and that the application is closed without saving on failure. This gives the agent important side-effect and failure-mode information.

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 with the core purpose, then follows with essential parameter and failure details. Every sentence contributes useful information, with no filler or repetition. The structure makes it easy for an agent to grasp the safety-critical behavior quickly.

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

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

The tool is complex with eight parameters, no output schema, and no annotations, so the description needs to be thorough. It covers the most distinctive parameters and failure behavior, but leaves required parameters task, section, and st_source unexplained. This creates enough ambiguity that an agent may not correctly construct a valid invocation without additional inference.

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

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

The description adds meaning for source_path, output_path, variables, and declare, which is valuable given 0% schema coverage. However, it does not explain the required task, section, or st_source parameters beyond their names, leaving a significant semantic gap for a complex tool with eight parameters.

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

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

The description opens with a specific, action-oriented statement: 'Safely edit ST logic and save only after a clean build, always to a copy.' This clearly identifies the verb (edit/save), the resource (ST logic), and the distinguishing constraint (always to a copy). It differentiates the tool from siblings like write_st_logic or build_project by emphasizing the copy-and-safety behavior.

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

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

The description gives clear operational context: source_path can be any member of a RemoteConnect bundle, output_path must be new unless overwrite=true, and failure closes the application without saving. It does not explicitly name alternative tools or state when not to use this tool, but the copy-safety intent makes the use case reasonably clear. This is just short of full routing guidance.

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

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

No annotations are provided, so the description carries full burden. It states 'Replace' but does not disclose side effects, reversibility, compatibility constraints, or any additional impact on the project. Given it's a mutation tool with zero annotation coverage, this is a significant gap.

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

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

The description is a single sentence, front-loaded with the action and resource, and includes an illustrative example without waste. Every word 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?

For a mutation tool with no output schema, no annotations, and two required parameters, the description is incomplete. It does not explain what happens after replacement, whether the tool returns a success/failure indication, or if any preconditions exist. The presence of many sibling hardware tools further demands clearer context to avoid misuse.

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

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

Schema coverage is 0%, so the description must compensate. It provides a concrete example ('BMX P34 2020' + '02.70') that hints at the format and relationship between part_number and version, but it does not explain how to obtain valid values (e.g., from get_hardware) or the full meaning of each parameter. This adds some value but is insufficient for a 0% coverage scenario.

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 ('Replace') and resource ('project's CPU'), with an example that disambiguates from sibling tools like replace_io_module or replace_rack. It does not explicitly contrast with siblings, but the resource is specific enough for an agent to differentiate.

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

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

The description implies when to use this tool (when a CPU replacement is needed) but does not provide explicit guidance on alternatives or exclusions. There is no mention of prerequisites (e.g., project must be open) or when not to use it, leaving usage context somewhat inferred rather than explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly warns that unsaved changes are discarded when save=False, which is the most important side effect of this action. It does not cover edge cases like closing when no project is open, but the core destructive behavior is clearly disclosed.

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

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

The description is two short sentences with no filler. The primary action is front-loaded, and the important caveat about unsaved changes appears immediately after. 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?

For a tool with one optional parameter and no output schema, the description covers the essential behavior and the parameter semantics well. It lacks only a small amount of context about alternatives or what happens if no project is currently open, but overall it is sufficiently complete for an agent to 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 for parameters is 0%, so the description must compensate for the 'save' parameter. It does: 'optionally saving first' and 'Unsaved changes are discarded when save=False' provide meaningful semantics beyond the raw boolean/default. It could have explicitly stated that save=True saves before closing, but the meaning is strongly implied.

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 action ('Close') and the resource ('the open project'), and it adds the optional save-first behavior, which differentiates this from save-only or open operations. It does not explicitly name a sibling tool to distinguish itself, so it falls just short of a 5.

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

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

The description implies when to use this tool — when the goal is to close the open project — and it explains the save=False consequence. However, it gives no explicit guidance about alternatives like save_project for saving without closing, or open_project for opening a different project, so the usage boundaries are 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?

No annotations are provided, so the description carries full burden. It discloses that the tool updates every stored copy, triggers a project-archive round-trip that reloads and marks the project UNSAVED, and can fail the build if certain service flags are disabled. This is rich behavioral context beyond 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 dense but every sentence adds value: purpose, parameter meanings, a failure condition, side effects with follow-up actions, and an alternative tool. It is well-structured and front-loads the core configuration scope.

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 12 parameters, no output schema, and no annotations, the description covers all essential information: parameter usage, side effects, failure conditions, and alternative routing. An agent has everything needed to call it correctly and interpret the aftermath.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the meaning of ip_a/ip_b/ip_d, the main IP/subnet/gateway, and the service flag semantics ('-1 = leave unchanged, 0 = disable, 1 = enable') along with defaults. This fully covers the parameter meanings.

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 'Configure' and the resource 'M580 CPU's embedded Ethernet', listing specific items (main IP/subnet/gateway, HSBY addresses, service flags). It immediately distinguishes itself from set_dtm_address by naming the alternative, so an agent can tell them apart.

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

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

It explicitly says when to use set_dtm_address instead ('For a slave device's gateway-domain warning'), and provides context on the CRA requirement and the need to run build_project/save_project after the side-effect round-trip. This gives clear when-to-use and when-not-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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the effect (shows live values) but does not disclose side effects, prerequisites, behavior on existing tables (beyond 'add to an existing one' without specifics), reversibility, or error conditions. For a mutating tool, this is a significant gap – the agent cannot anticipate what happens if the table already exists or what permissions are needed.

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

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

The description is two sentences, front-loads the action, and includes a helpful example for the variables parameter. No redundant fluff. The structure is clear and efficient, though the second sentence explaining variables could be seen as an implementation detail that might belong elsewhere, but it earns its place.

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

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

For a tool with 2 parameters, no output schema, and 0% schema coverage, the description provides the core purpose, an example, and the context (online requirement). However, it omits details about the 'name' parameter, what happens on conflicts, and how to interact with the table after creation (though a sibling open_animation_table exists). This leaves gaps that could mislead an agent into incorrect calls.

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

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

Schema description coverage is 0%, so the description must explain both parameters. It explains 'variables' well: 'variables is a comma-separated list of variable names' with an example. However, it does not explain the 'name' parameter at all, leaving its role (table name) implicit. It adds value for one of two parameters, but the other remains undocumented in both schema and 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 'Create an animation table (or add to an existing one) and fill it with variables to watch.' This gives a specific verb (create/add), a resource (animation table), and an action (fill with variables). It distinguishes from siblings like list_animation_tables (list), delete_animation_table (delete), and open_animation_table (open) by implying creation/modification. No ambiguity.

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 provides a clear usage context: 'With the project online (simulator or PLC), the table shows live values in the Control Expert UI.' This implies the tool is used for live monitoring. It also covers both creating and adding, which are the two primary use cases. However, it does not explicitly mention alternatives or when not to use it, but the verb and examples make it contextually 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?

With no annotations, the description carries the full behavioral burden and does so well: it discloses that the template is never modified, that the generated XLS is reopened and structurally checked, and that semantic validation is deferred to a later step. It also surfaces the constraint that match must select exactly one existing row.

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

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

The description is front-loaded with the core purpose and every subsequent sentence earns its place: patch semantics, the exact-match constraint, a concrete example, template safety, and validation expectations. It is dense but 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?

Given the absence of annotations and output schema, this is a complete contract: it explains the patch format, the row-matching rule, side effects on the template, structural checking, and the required follow-up validation step. An agent has enough to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does for the complex patches parameter by specifying the {sheet, match, values} shape and giving a concrete example, but template_path, output_path, and overwrite are left to their names and schema 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 description opens with a specific verb and resource: 'Create a patched copy of a RemoteConnect Object Bulk Edit workbook.' It clearly distinguishes this from sibling inspection/validation tools by emphasizing creation of a patched copy and the final validation route through read_remoteconnect_feedback.

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

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

It gives concrete usage context: how patches are structured, the exact-match requirement, and that the template is never modified. It doesn't explicitly enumerate sibling alternatives, but it tells the agent that RemoteConnect import plus read_remoteconnect_feedback is needed for final semantic validation, which implies when this tool is insufficient.

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?

No annotations are provided, so the description carries the full burden. It clearly signals mutation ('create') and the empty-state behavior, but does not disclose potential side effects such as duplicate-name failures or required task existence.

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 primary purpose, then efficiently organizes workflow guidance into scannable bullets. Every sentence provides actionable value without repetition 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?

For a simple creation tool with no output schema or annotations, the description covers the main workflow well, including language-specific fill strategies. It lacks minor context such as naming constraints and failure behavior, but overall an agent has enough to invoke it effectively.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for the language parameter by listing ST, LD, FBD, SFC, IL, and LL984, and explains how language affects the filling workflow. However, task and name semantics remain only inferable from their property titles.

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 action and resource: 'Create a new empty program section in a task.' The addition of 'empty' clarifies the tool's narrow role and distinguishes it from write_st_logic and import_xml, which populate logic.

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 explains when to use this tool versus alternatives: ST logic should go through write_st_logic, while LD/FBD/SFC should use get_language_reference then import_xml. This gives an agent clear routing across sibling tools.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It explains the effect of periodicity_ms (makes the task periodic), which gives some operational insight, but it says nothing about side effects, return values, error handling, permissions, or whether calling it multiple times replaces or creates multiple tasks. This is only a partial disclosure for a mutation operation.

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

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

Two sentences, no filler. The first sentence states the purpose, and the second sentence packs all essential parameter details. Every word earns its place, 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 both parameters and the core purpose, which is sufficient for a simple creation tool. However, with no output schema and no annotations, there is no guidance on what a successful response looks like, what happens on failure, or whether task names are auto-generated. These gaps are non-critical but present, so it falls short of fully complete.

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

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

Schema coverage is 0%: the schema merely says task_type is a string and periodicity_ms is an integer. The description compensates fully by enumerating allowed task_type values (MAST, FAST, AUX0..AUX3, SAFE) and defining periodicity_ms semantics (>0 makes the task periodic). This is exactly the kind of parameter meaning an agent needs to call correctly.

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

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

The description opens with a clear verb and object: 'Add a task to the project.' It also lists the specific task_type values, which immediately differentiates this from sibling create_* tools like create_variable, create_section, or create_animation_table. An agent can tell it is for adding a task without ambiguity.

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

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

The description implies when to use this tool: whenever a task must be added to the project. It does not name alternatives or exclusions, but none are needed because there is no other task-creation sibling. The context is clear enough to select it over other create_* tools.

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

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

With no annotations provided, the description must disclose behavioral traits. It only implies a write operation ('Create') without detailing side effects, reversibility, or error conditions. There is no mention of what happens on duplicate names, or required permissions, so behavioral transparency is minimal.

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 and front-loaded with the purpose, then details two key parameters efficiently. It avoids redundant phrasing, but the brevity comes at the cost of completeness for other parameters. Still, the structure is clear and focused.

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 5 parameters, no output schema, and no annotations. The description only covers two parameters and omits usage context, expected return, and any prerequisites or side effects. For a create operation, this is noticeably incomplete for an agent to rely on.

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

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

The schema has 0% description coverage, so the description must compensate. It explains type_name and address thoroughly, but name, comment, and initial_value are left undocumented. This partial coverage is insufficient for a 5-parameter tool with no schema descriptions for the remaining parameters.

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

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

The description states 'Create a global variable' clearly, with a specific verb and resource. It doesn't differentiate from sibling tools like update_variable or delete_variable, but the creation intent is unambiguous. It also gives examples of type_name and address, which adds clarity to the parameter semantics.

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

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

There is no guidance on when to use this tool vs alternatives, nor any exclusions or prerequisites. The description only explains parameter formats, not the usage context or selection criteria. This leaves the agent to infer when creation 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the destructive action ('delete') without disclosing permanence, irreversibility, preconditions (e.g., table must exist or not be in use), or failure behavior. The word 'delete' implies destruction but offers minimal safety 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 a single concise sentence with no filler. It front-loads the action and resource, making it immediately clear and efficient.

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

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

For a one-parameter delete operation, the description covers the core action and parameter identification. However, without annotations or an output schema, it omits safety warnings, error behavior, and any preconditions, so the context is not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does indicate that the 'name' parameter identifies which animation table to delete. However, it provides no additional constraints, format, or existence requirements beyond the schema's basic string type.

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

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

The description states a specific verb ('delete') and resource ('animation table'), and identifies the key parameter ('by name'). It clearly differentiates this tool from sibling tools like create_animation_table, list_animation_tables, and open_animation_table.

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

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

The description implies when to use the tool (when you want to delete an animation table) but provides no explicit guidance on alternatives or exclusions. It does not mention that listing or opening tables might be preferable in certain contexts.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It explicitly reveals the key side effect: deleting a DTM also deletes its children. It does not mention irreversibility or permissions, but the destructive scope is clearly stated.

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

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

The description is a single compact sentence with no filler. The operation and resource are front-loaded, and the parenthetical scope note efficiently communicates the most important nuance.

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

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

For a one-parameter, no-output-schema tool, the description covers the target resource, the selection mechanism, and the destructive scope. It could add an explicit warning about irreversibility or return behavior, but the definition is otherwise sufficient for correct invocation.

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

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

The schema provides only a string parameter named 'name' with no description (0% coverage), so the description must supply meaning. The phrase 'by name' tells the agent that the required parameter identifies the DTM to delete. It does not detail name matching rules, but that is unnecessary for a single simple parameter.

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

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

The description states a specific verb ('Delete'), a concrete resource ('DTM'), the scope ('and its children'), and the selection criterion ('by name'). This clearly distinguishes it from sibling deletion tools like delete_variable or delete_section.

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 clear context: use this tool to remove a DTM and its children from the topology by name. It does not explicitly name alternatives or state exclusions, but the resource scoping is unambiguous enough for an agent to select it correctly.

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

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

With no annotations, the description bears the full responsibility for disclosing behavioral traits. It names the action as 'Delete', which implies destructiveness, but offers no additional context about irreversibility, permissions, or side effects. The minimal verb does not meet the bar set for unannotated 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?

The description is a single, concise sentence with no filler, but it is under-specified rather than appropriately concise. While the structure is clear, the brevity omits necessary detail, making it less helpful than a more complete but still efficient description.

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 only two string parameters and no output schema, the description still lacks essential context. It does not explain what a 'section' is, what constitutes a valid 'task', or any error conditions. The absence of parameter descriptions and behavioral notes leaves the agent with insufficient information to call it reliably.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. However, it provides no information about the 'task' or 'section' parameters, their expected formats, or how they relate to the operation. The description adds zero value over 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?

The description clearly states a specific action (Delete), resource (program section), and context (from a task). It distinguishes from sibling tools like create_section and read_section, establishing its destructive purpose without ambiguity.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description does not mention scenarios where deletion might be disallowed or conditions for use, leaving the agent to infer context from the name alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action without mentioning side effects, reversibility, permission requirements, or error handling. For a destructive operation, this missing context is a significant gap.

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

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

The description is a single, well-structured sentence with no filler words. It is front-loaded and efficiently communicates the core action. There is no unnecessary verbosity or repetition.

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

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

For a simple delete operation with one parameter and no output schema, the description is incomplete. It does not address what happens if the variable does not exist, whether deleting it affects references, or what the response looks like. This is a low-complexity tool, but the lack of behavioral context makes it insufficient for an agent to invoke safely.

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

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

The schema has a single required parameter 'name' of type string, and the description says 'by name' which loosely references it. However, it adds no meaningful detail beyond the schema, such as format, case sensitivity, or uniqueness. With 0% schema description coverage, the description does not compensate.

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 action (delete), the target resource (global variable), and the selection method (by name). It is unambiguous and distinct from sibling tools like create_variable or update_variable, so an agent can easily tell what this tool does.

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 no guidance on when to use this tool versus alternatives like update_variable or list_variables. It does not mention conditions, prerequisites, or when deletion is appropriate, leaving the agent to infer the use case from the name and 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?

With no annotations provided, the description carries the full disclosure burden. It clearly states that the operation is an export to an XML exchange file, but it does not mention overwrite behavior, whether a project must be open, or what side effects may occur at the destination path.

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

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

The description is a single, focused sentence that front-loads the action, resource, and output format. It earns its place without repetition or filler.

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

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

For a simple one-parameter tool, the description covers the core operation and rationale, but it leaves path semantics and potential side effects underspecified. Since there is no output schema and no annotations, those details would be needed for fully confident invocation.

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

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

Schema description coverage is 0%, so the description must explain the single 'path' parameter. It only implies that path is the export destination; it does not clarify whether the extension determines .xef vs .zef, whether the path should include the filename, or any path constraints.

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

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

The description states a specific verb ('Export'), a clear resource ('the full application'), and the exact output format ('.xef or .zef XML exchange file'). This clearly distinguishes it from sibling tools like export_xml, which would be expected to handle a narrower XML export.

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

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

The description gives concrete use cases: backup, diffing, or migrating between Control Expert versions. It does not explicitly name alternatives or state when not to use it, but the provided context is enough for an agent to decide when this tool 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses a critical side effect: 'Large exports are written to a temp file and the path is returned instead', which is exactly the kind of behavioral nuance an agent needs to handle the response correctly. It could add detail on cleanup of temp files or exact size thresholds, but the core behavioral variation is clearly stated.

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 but the kind enumeration is packed densely in a few sentences without line breaks, making the conditional dependencies less scannable. It could be more readable with bullets or separators, though it's not bloated — every sentence carries information.

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

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

For a tool with 3 params, 0% schema coverage, and no output schema, the description covers the enum values, their parameter requirements, and the variable return behavior. The main gaps are the exact threshold for 'large exports' and temp-file cleanup semantics, but for an agent selecting and invoking the tool, the essential information 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?

The schema has 0% description coverage and no enum values for 'kind', yet the description fills this gap comprehensively by documenting each allowed value and its dependencies ('dfb' requires name, 'section' requires task and name). This fully compensates for the empty schema and gives the agent what it needs to construct valid calls.

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

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

The description states a specific verb ('Export'), a specific resource ('project content as Control Expert XML'), and a clear return behavior (inline or file path). It enumerates the five accepted kind values and their accompanying required parameters, which unambiguously distinguishes this tool from siblings like import_xml, validate_xml, and export_project.

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

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

The description explains when each kind is appropriate ('all variables', 'all program logic', etc.) and which parameters are required for each sub-case. It doesn't explicitly name competing sibling tools or state when NOT to use it, but the kind enumeration provides clear selection guidance for the primary use case.

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

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

With no annotations provided, the description must carry the burden of disclosing side effects and prerequisites. It says 'Read', implying a read-only operation, but does not state whether it requires an open project, whether it is non-destructive, or what error conditions may occur. The output format is specified, but behavioral traits are understated.

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

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

The description is a single, well-structured sentence that front-loads the action and resource, then lists details concisely. No extraneous information is present.

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?

While the output format is detailed (XML with schema and components), the lack of parameter explanation and absence of any prerequisites or behavioral notes makes the description incomplete for a one-parameter tool. It does not compensate for the missing parameter semantics.

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

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

Schema description coverage is 0%, so the description must explain the 'name' parameter. It does not mention what 'name' refers to (e.g., the DTM's name), leaving the agent without sufficient guidance to correctly supply the parameter.

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

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

The description clearly states the tool reads a master/communication DTM's control parameters and specifies the exact content (Modbus TCP I/O scanner lines, addresses, sizes). It distinguishes itself from write counterparts by using the verb 'Read', though it does not explicitly contrast with get_dtm_dataset or other read tools.

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

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

The description implies the usage context—when you need control parameters of a master/communication DTM—but does not explicitly mention when not to use it or mention alternatives like set_dtm_control_parameters for writes. The guidance is implied, not explicit.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden, and it does so well. It reveals the binary-framed FDT container format, explains that the returned XML is not byte-faithful, and warns against editing and writing it back. This is valuable beyond anything in the schema or 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 three sentences, each earning its place: purpose, format/caveat, and sibling routing. It is front-loaded with the core behavior and avoids filler.

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

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

For a one-parameter tool with no output schema, the description covers purpose, behavioral caveats, and alternatives impressively well. The only notable gap is the ambiguous 'name' parameter, which prevents fully confident invocation without additional inference.

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

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

The schema provides only a required 'name' string with no description, and schema coverage is 0%. The description never explains what 'name' should be, such as a DTM path, identifier, or display name, so the agent must infer the parameter semantics from context.

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: 'Export a slave DTM's configuration dataset for INSPECTION.' It clearly differentiates from sibling tools like get_master_dtm_dataset and set_master_dtm_dataset by naming them explicitly.

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

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

It states when to use the tool (for inspecting/exporting a slave DTM dataset) and explicitly routes to alternatives for M580 Modbus scan lines. It also warns against writing the result back via set_dtm_dataset, which is a clear exclusion.

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

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

With no annotations available, the description carries the full behavioral burden. It clearly conveys a non-mutating operation through 'List' and specifies the data returned, though it does not mention prerequisites such as requiring an open project or operational caveats.

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

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

A single, information-dense sentence that front-loads the action before specifying the hierarchical contents. Every element earns its place with no 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 zero-parameter read-only listing tool, the description provides a solid high-level account of the return content, including the topology tree, part numbers, versions, and addresses. It omits an explicit prerequisite like needing an open project, and there is no output schema to fill that gap, but the core invocation is still clear.

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

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

The tool takes zero parameters and the input schema is empty, so there is nothing for the description to explain. Per the zero-parameter baseline this is appropriate.

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

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

The description states a specific verb ('List') and a precise resource ('full hardware configuration') and enumerates the exact contents: CPU plus the bus → drop → rack → module tree with part numbers, versions and topological addresses. This is sufficiently distinct from hardware mutation siblings like add_drop or replace_rack.

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

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

The description implies use for reading the complete hardware inventory, and the read-only 'List' verb makes it distinguishable from mutation tools, but it never explicitly states when to use it over alternatives or what not to use it for. No exclusions or alternative routing are provided.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the output is validated against a live Control Expert build, that the example imports and builds with 0 errors, and that the tool is a read-only reference step. It doesn't explicitly state 'does not modify state', but the workflow and wording make this clear enough.

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

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

The description is dense and front-loaded with 'REQUIRED READING', then clearly states the return value, workflow, and alternative. Every sentence adds value; the workflow is a succinct but complete sequence. It is longer than some examples, but no part is 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 a one-parameter tool with no output schema, the description fully explains what the tool returns (structure rules + example section) and how to use it in the larger workflow. The integration with import_xml and write_st_logic makes it contextually complete for an agent deciding to call it.

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

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

The schema has a single parameter 'language' with no description and no enum, so the description must compensate. It does by listing the allowed languages ('ST', 'LD', 'FBD', 'SFC', 'IL') and providing guidance on ST via write_st_logic. This gives strong semantic meaning, though it doesn't explicitly map the parameter to the list.

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 returns a language-specific authoring guide and exchange-XML structure rules, including a validated example section. It distinguishes itself from siblings by explicitly naming write_st_logic as an alternative for ST, so an agent can tell them apart.

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 provides an explicit workflow ('read this guide -> write the section XML -> import_xml -> build_project -> fix errors') and an explicit exclusion: 'For ST, prefer the write_st_logic tool (no XML needed).' This tells the agent exactly when to use this tool and when not to.

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

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

With no annotations provided, the description carries the behavioral burden. It reveals that dtm defaults to the first CPU node and describes the XML structure in detail, showing this is a read operation on the master dataset. It does not cover error behavior or side effects, but for a read-only tool the essential 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 description is front-loaded with the primary purpose and then provides relevant structural detail about the XML document. The XML breakdown is dense but useful given the lack of an output schema. It is not overly verbose and every section serves a purpose.

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 the key context: what the dataset represents, how it is structured, and the default behavior of the only parameter. It lacks details about error cases and valid dtm values, but for a read tool with a single optional parameter, the provided context is largely sufficient.

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

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

The input schema provides only a bare optional string with default '', and schema_description_coverage is 0%. The description adds meaning by associating dtm with the DTM node and explaining the default CPU behavior, but it does not specify how to reference non-default DTMs or what formats are accepted. This partial compensation keeps it above baseline but leaves a gap.

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

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

The description clearly identifies the action ('Read') and the specific resource ('master/CPU DTM dataset XML'), and elaborates on its content (Modbus TCP scan lines). It distinguishes itself from generic DTM reads by emphasizing the master/CPU scope, though it does not explicitly name conflicting siblings.

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

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

The description implies its usage by stating what it reads and noting the default DTM node, but it does not provide explicit when-to-use versus alternative tools like get_dtm_dataset or set_master_dtm_dataset. The context is clear for the master dataset case, but no exclusions or alternative routing is given.

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

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

With no annotations, the description carries the full burden. It explicitly states this is a read operation, and it adds useful context about how idents can be located in exported .xef files. However, it does not describe return format, error behavior, or what happens when the ident is not 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?

The description is two sentences, front-loaded with the core action and resource, followed by valuable examples and context. Every word contributes, with no redundancy or filler.

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

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

For a simple getter with one parameter and no annotations or output schema, the description covers the essential aspects: what the tool does, how the parameter is used, and where to find idents. Minor gaps include explicit return-value description and error behavior, but these are not critical for such a straightforward 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 has 0% description coverage, but the description compensates well by defining 'ident' as a project setting identifier, providing concrete examples, and explaining where to find valid idents in exported .xef files. This meaningfully goes beyond the raw schema property name.

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

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

The description clearly states the tool 'reads' a project setting value by its identifier, which is a specific verb and resource. This naturally distinguishes it from sibling tools like set_project_settings, which writes rather than reads.

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

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

The description implies usage: use this tool when you need to read a project setting and have its ident. It also provides helpful context about where idents appear in exported .xef files, but it does not explicitly mention when not to use it or directly compare with 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?

No annotations are supplied, so the description bears the full burden of behavioral disclosure. It implies a read-only operation but doesn't explicitly state that, nor does it mention any prerequisites (e.g., an open project) or performance implications. Minimal behavioral context beyond the obvious read nature.

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

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

A single, focused sentence that leads with the action ('List the program structure') and then specifies the exact return elements. No filler, no redundancy, and perfectly efficient for the agent to scan.

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

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

Given the tool's simplicity (no parameters, no output schema), the description adequately explains the return values: tasks, scan settings, sections with IEC language, and counts. It does not mention prerequisites or error conditions, but for a read-only overview tool these are minor; the core information 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?

The tool has zero parameters, so the schema already covers everything (100% coverage). Per rubric, a zero-parameter tool gets a baseline of 4; the description adds no parameter-specific information, but none is needed. No ambiguity exists.

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

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

States a specific verb ('List') and resource ('program structure'), then enumerates the exact contents: tasks with scan settings, sections with IEC language, and counts of events and functional modules. This clearly differentiates it from siblings like get_status or list_variables, which serve different 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 provides no guidance on when to use this tool versus alternatives. It merely describes functionality without mention of use cases, prerequisites, or exclusions. The agent must infer when to call it, which is a notable gap.

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

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

With no annotations, the description must carry the behavioral burden. 'Get' implies a non-mutating read, and it lists what information is returned. However, it does not explicitly state that the tool has no side effects, nor does it disclose any potential errors or prerequisites, leaving some ambiguity for an agent.

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

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

The description is a single, well-formed sentence that front-loads the action and then lists the return fields. Every word adds value; there is no redundancy or 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?

The description enumerates the specific items returned (server version, project-open state, file path, CPU, version, build state), which tells an agent what to expect. It does not specify data types or formats, but for a status tool without an output schema, this is sufficient for basic invocation. It could mention that the output is a summary, but it is otherwise 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 tool has zero parameters, so the schema is trivially complete (100% coverage). The description adds no parameter-level detail because none is needed; the baseline of 4 is appropriate since there is nothing to augment.

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 clear, specific action: 'Get the current session status' and enumerates the exact data returned (server version, open project, file path, CPU, version, build state). This is unambiguous and distinct from sibling tools like open_project or build_project, which perform different actions.

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

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

The description implies this is a read-only status query for the current session, but it does not explicitly state when to use it versus alternatives or any preconditions. Given the sibling set, no other tool retrieves session-level status, so usage is somewhat self-evident, but the description offers no explicit 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?

No annotations are present, so the description carries the full burden of disclosure. It does disclose import_mode semantics (overwrite default vs keep_existing vs rename), warns that 'Control Expert validates the schema strictly', and reveals that build_project will list per-section errors to fix. It stops short of stating permission/auth requirements or the direct success/failure return of the call itself, but given the burden it carries, the disclosure is solid rather than complete.

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

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

The description is long but every sentence earns its place for a 5-parameter, multi-workflow tool. It front-loads the core purpose, then parameters, then the prescriptive authoring workflow, then the template tip. No filler or tautology.

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 high complexity (multiple kinds, dependencies on sibling tools) and the thin schema with no output schema, the description is nearly complete: it covers purpose, all parameter semantics, workflow ordering, and alternatives. The residual gap is that it never states what import_xml directly returns on success/failure (the agent must infer error handling from the build_project step), and it assumes an already-open project is understood.

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

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

Schema description coverage is 0%, so the description fully compensates: it enumerates and explains the kind values ('section' requires task, 'project' is a generic exchange-file import), distinguishes xml_content vs file_path as two delivery mechanisms, and documents import_mode with its default and allowed values. This exceeds what the bare schema provides and directly 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?

The description states a specific verb ('Import') plus its resource ('Control Expert XML into the open project') and names the primary scope ('the main way to write LD/FBD/SFC program logic and bulk content'). It distinguishes itself from siblings by explicitly routing Structured Text authoring to write_st_logic instead, so an agent can tell it apart from related tools without opening schemas.

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

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

Explicit use-context is given: for kind='section' it prescribes an ordered workflow (get_language_reference → validate_xml → import), names the alternative for ST (write_st_logic, 'no XML needed'), and mandates the follow-up build_project step. It even suggests export_xml / read_section as a template prerequisite. The when-versus-alternative guidance is complete and unambiguous.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that this is a read operation, lists what is returned, and adds a meaningful warning about row-2 vs row-1 fields, which affects subsequent patch creation. It does not cover error behaviors or file-format details, but those are less critical for a read-only inspector.

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

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

Three compact sentences, no filler, with the core action first and the most actionable usage warning last. Every sentence adds 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?

Given no output schema, the description provides a reasonable high-level account of the return value: version/DTM metadata, every sheet's stable machine fields, and optional data rows. It is enough for an agent to invoke the tool correctly, though the exact structure of the returned metadata is not specified.

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

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

Schema description coverage is 0%, so the description must compensate. It explains sheet_name and limit ('Pass sheet_name to also return up to limit data rows') and implicitly ties path to the workbook being read. However, the path parameter itself is not explicitly described, and no additional detail is given about format, constraints, or defaults beyond what the schema shows.

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: 'Read a native RemoteConnect Object Bulk Edit `.xls` workbook.' It further clarifies the output (version/DTM metadata and stable machine fields) and is clearly distinct from the sibling create_remoteconnect_bulk_edit_copy, which writes rather than reads.

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

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

It gives concrete usage direction: 'Pass sheet_name to also return up to limit data rows' and instructs to use row-2 machine fields rather than translated row-1 labels. It does not explicitly contrast with alternative tools, but the read-vs-create sibling split and parameter guidance make the intended use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It states the tool does not open or modify files, returns sibling files and a safe summary, and explicitly notes that opaque DTM EngineeringData is counted but never deserialized or changed. This clearly communicates the operation's safety boundaries.

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, opening with the core behavior before giving supporting detail. Every sentence adds relevant information, and there is no filler or 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 single-parameter inspection tool with no annotations and no output schema, the description covers the accepted file types, the action taken, the return content, and the key safety constraint. It is slightly incomplete in not addressing sibling-tool differentiation or potential error conditions, but overall it gives an agent enough to invoke the tool correctly.

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

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

The input schema only provides the parameter name 'path' with no description, so the description must compensate. It does by explaining that path may identify a .PRJ, .RCZ, .STU, or .STA file, adding meaningful context beyond the bare schema. It does not fully specify path formatting details, but for a single-path parameter this is useful and sufficient.

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 inspects a RemoteConnect project bundle without opening or modifying it, and names the accepted file types. It does not explicitly distinguish itself from closely named siblings like analyze_project or get_project_structure, but the 'without opening or modifying' phrasing and focus on bundle inspection make the core 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 implies the tool is for safe, non-modifying inspection of project bundles, which signals when to choose it over open_project or modification tools. However, it does not explicitly state when to use this tool versus alternatives such as analyze_project or get_project_structure, nor does it mention any exclusions.

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

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

With no annotations, the description carries the full burden and does well: it explicitly states 'never performs unsafe .NET deserialization or modifies the project' and notes that record values are opaque. This provides meaningful safety-related context beyond the name and schema, though it omits other behaviors like path validation or error handling.

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

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

The description is compact and well-structured: the first sentence states the core purpose and return, while the second adds safety and output characteristics. Every sentence contributes value with no redundancy or 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?

While the description covers the tool's read-only nature and high-level return content, it critically misses the meaning of the required 'path' parameter and any usage context. Since there is no output schema and only one parameter, the description should explain that parameter to be considered 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 only parameter 'path' has zero schema description coverage and the description never explains what 'path' refers to, its format, or how it should be provided. The agent is left without any information to populate the sole required parameter correctly.

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

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

The description states a specific verb ('Read') and resource ('RemoteConnect FDT/DTM topology and configuration-object index'), and clarifies the return value ('every DTM identifier and its InstanceDataRecord groups'). However, it does not explicitly differentiate itself from siblings like list_dtms or inspect_remoteconnect_project, so it falls short of a 5.

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

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

No guidance is given on when to use this tool versus alternatives. Although the description implies a read/inventory use case, it does not state exclusions, prerequisites, or reference sibling tools, leaving the agent to infer selection 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?

With no annotations, the description carries the burden of explaining behavior. 'List' strongly implies a read-only operation and the parenthetical provides conceptual context, but the description does not explicitly state that no side effects occur or describe the return format.

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

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

A single, front-loaded sentence states the action and adds only the necessary definition of animation tables. No wasted words or redundant schema repetition.

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

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

For a zero-parameter listing tool, the description is sufficient to understand what the tool does and when to call it. It could be more complete by noting that this is a non-mutating, project-scoped read operation, but nothing essential 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?

The tool has zero parameters and 100% schema coverage, so there is no parameter detail for the description to add. Baseline 4 applies because no parameter information is missing.

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

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

The description uses a specific verb ('List') and resource ('the project's animation tables'), and the parenthetical ('watch tables used to monitor and force variable values online') clarifies exactly what animation tables are. This distinguishes it from sibling tools like create_animation_table, delete_animation_table, and open_animation_table.

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

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

The description makes the intended usage context clear: use this tool to obtain the project's animation tables. It does not explicitly name excluded alternatives or state 'use X instead', which keeps it just below a 5.

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

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

No annotations are provided, so the description carries the full burden. It states the action (list) and the output content (types with versions), which implies a read-only operation, but it does not explicitly confirm that there are no side effects or mention any error scenarios or limitations. For a simple list tool, this is adequate but not rich in behavioral detail.

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

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

The description is a single, well-structured sentence that front-loads the verb and resource, then adds the specific categories and version detail. There is no wasted wording, and every element adds meaning.

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

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

For a zero-parameter tool with no output schema, the description is reasonably complete: it tells the agent what the tool does and what kind of information it returns (types with versions). It does not specify the exact return structure (e.g., fields or format), but for a simple listing operation this is acceptable. The description could be slightly richer by noting if the list is sorted or if it only returns current versions, but it is sufficient for correct invocation.

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

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

The tool has zero parameters, so the description need not explain any parameter semantics. The schema strongly covers the empty parameter list, and the description adds the context that the listing is for 'user data types' and includes versions, which is useful. Baseline for 0 params is 4, and the description does not need to compensate further.

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 'List' and the resource 'user data types in the project', and explicitly enumerates two categories (DFB types and DDTs) with their versions. This is specific and distinguishes it from sibling tools like list_variables (which lists variables, not types) and get_project_structure (which describes the overall project).

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

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

The description implies when to use the tool (when you need to list data types) but offers no explicit guidance on alternatives or when not to use it. It does not compare with list_variables or other list operations, relying on the reader to infer the distinction. Given the large sibling set, some explicit routing would be beneficial, but the purpose is clear enough to deduce 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It accurately describes the output content without implying side effects. The verb 'List' inherently signals a read-only operation, and the description includes the exact fields returned, which is key behavioral transparency. However, it does not state anything about prerequisites (e.g., project must be open) or potential error conditions, though for a zero-parameter tool these are less critical.

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

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

The description is a single, dense sentence that leads with the action and resource, then immediately details the content of the output. It contains no filler or repetition—every clause adds value. This is exceptionally concise while still being informative.

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 zero-parameter read tool with no output schema, the description is sufficiently complete. It specifies the primary data fields returned and the scope (communication/master DTMs and slaves). It does not describe the exact format (e.g., list vs. hierarchical tree), but 'topology' implies structure and the fields listed give a clear idea of the result. An agent can call this tool with confidence about what to expect.

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?

There are zero parameters, so the schema has full coverage by default. The description doesn't need to add parameter information; the tool takes no input. The baseline for zero-parameter tools is 4, and the description appropriately focuses on output rather than inputs.

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 the verb 'List' and the resource 'project's DTM topology', and enumerates the specific data returned (names, DTM ids, types, bus addresses). This distinctly separates it from sibling tools like add_dtm, set_dtm_address, or delete_dtm, which are mutation 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?

The description gives clear context for when this tool is applicable—when an agent needs to inspect the DTM topology. It does not explicitly state when not to use it or name alternative tools, but the listing nature and the specificity of 'DTM Browser' make the purpose unambiguous. No exclusions are provided, but it's easy to infer that alternatives like get_hardware or list_networks are for other perspectives.

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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It clearly indicates a read-only listing operation and adds the conditional detail that IP service configuration is included only 'where available'. This is sufficient transparency for a simple list operation.

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

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

The description is a single, front-loaded sentence with no filler. Every phrase contributes either the resource, its scope, or the conditional output content.

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

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

For a zero-argument list operation, the description fully covers what is being listed, the relevant hardware families, and the availability of IP service configuration. No output schema exists, but the return content is sufficiently implied by the description.

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

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

The tool has zero parameters, so there is nothing for the schema to explain. The description adds semantic context by specifying which types of logical networks are listed, which is helpful despite the absence of parameters.

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

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

The description uses a specific verb ('List'), identifies the resource ('logical networks'), and enumerates the scope (Premium/Quantum: Ethernet, Modbus Plus, Fipway). This clearly distinguishes the read-only list operation from mutating sibling tools like add_network and set_network_ip.

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 intended usage is implied by 'List' and the network-focused description, but there is no explicit when-to-use or when-not-to-use guidance and no named alternatives. An agent can infer when this tool is appropriate, but the description does not state it directly.

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?

No annotations are provided, so the description carries the full burden. It makes the read-only nature clear with 'List' and discloses the case-insensitive substring filter behavior. It does not mention prerequisites such as requiring an open project, result ordering, or pagination handling.

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

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

The description is two sentences, front-loaded with the core behavior and followed by the filter detail. There is no filler or redundant restating of the tool name.

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

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

For a simple read-only list tool with two optional parameters, the description covers the relevant output fields and the filtering behavior well. Minor gaps are the lack of explanation for max_results semantics and the absence of an explicit output format, but these are not critical given the simplicity.

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

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

Schema description coverage is 0%, so the description must compensate. It explains name_filter's case-insensitive substring matching, which adds real meaning beyond the schema. However, it leaves max_results undocumented beyond its default 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 states a specific verb ('List') and resource ('global variables') and enumerates the returned attributes: type, comment, topological address, and initial value. It clearly distinguishes this read-oriented listing tool from sibling tools like create_variable, update_variable, and delete_variable.

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

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

The description implies when to use the tool: when one needs to enumerate global variables, optionally filtered by name. However, it does not explicitly mention alternatives or provide when-not-to-use guidance, such as when to use list_data_types instead.

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

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

With no annotations, the description carries the full burden and discloses key non-obvious behaviors: the project exists only in memory until save_project is called, the project name is inherited from the .stu filename, and there is no settable project-name field. It also states exact-match requirements against the catalog, which is important acceptance behavior.

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

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

The description is front-loaded with a one-sentence purpose, then gives focused parameter constraints and the critical persistence trait. Every sentence adds value; there is no filler.

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

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

The description covers invocation parameters, required catalog matching, and the in-memory-then-save lifecycle, which is sufficient for correct calling. It does not describe return values or error behavior, and with no output schema some agents might want that, but it does not compromise 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 schema has 0% description coverage, so the description fully compensates by detailing both parameters: cpu_part_number must exactly match a catalog CPU reference with examples, and cpu_version is the required firmware version offered by the catalog with an example. This is more than enough to invoke the tool correctly.

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

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

The description opens with a specific verb and resource: 'Create a new project from scratch for a given PLC CPU.' This clearly distinguishes it from open_project and change_cpu, and the subsequent save_project reference further disambiguates the lifecycle.

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

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

It establishes clear context for when to use: creating a new project rather than opening an existing one, and it names save_project as the follow-up for persistence. It does not explicitly list when not to use it, but the 'from scratch' framing and memory-only caveat provide enough 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 are absent, so the description must carry the burden. It discloses that the GUI opens read-only while the client keeps write, and that the table animates live once connected. This is critical behavioral context: it tells the agent that this tool has no write side-effects and that the animation depends on an active connection. It also implies a step dependency (must be connected) which is not in annotations. Missing a bit about failure modes or exact GUI behavior, but overall strong.

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 written, with three sentences. The first states purpose and key context, the second gives the usage flow, the third explains read-only and live animation. No filler. It's structured logically: what, when, and behavioral notes. Efficient.

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 (2 params, no output schema), the description covers the main usage context and behavior. The main gap is explaining the parameters, especially 'state', and what the return/result of the call is (though it's a GUI opener, so no output is fine). The typical flow and read-only behavior are excellent. Slightly incomplete on parameter semantics and edge cases, but overall adequate.

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

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

Schema coverage is 0%, and the description doesn't explain the parameters at all. 'name' likely refers to the table name, but it's not stated; 'state' with default 'show_normal' is entirely unexplained. The agent must infer what 'state' means (e.g., window state, display mode). The description only mentions 'open' and 'editor', not parameter details. Since schema provides only titles and types, this is a significant gap.

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

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

Description is very specific: 'Open an existing animation table's editor inside the live Control Expert window' clearly states verb (open), resource (animation table editor), and context (live window). It differentiates from creation/deletion siblings by focusing on opening existing tables. The typical live-test flow provides strong distinction from list_animation_tables (which lists names) and create_animation_table.

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

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

The description explicitly gives the typical live-test flow: create_animation_table -> start_simulator ->_connect -> plc_transfer -> plc_command('run') -> open__table. This tells the agent exactly when to call this tool – after the simulation is running and connected. It also states that the GUI opens read-only and that this client keeps write, implying when to use it (for live monitoring) vs. other write operations.

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?

No annotations are provided, so the description carries full disclosure burden. It clearly warns that any previously open project is closed without saving, explains that XML formats are imported fresh, and sets expectations for long opening times (30-120 s). This is strong behavioral transparency for a state-changing tool.

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

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

Three concise sentences, each providing useful information: the action, supported formats, and two important behavioral caveats. No filler or redundant 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?

Given no annotations and no output schema, the description covers the key aspects needed to call the tool correctly: what it opens, which formats are supported, the destructive close-without-save behavior, and expected latency. Nothing critical 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 0% and the schema only says 'path'. The description adds meaningful parameter context by specifying that the path can point to .stu, .sta, .xef, or .zef files, and that certain formats are imported differently. It does not fully define path syntax but compensates well for a simple single-parameter tool.

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

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

States a specific verb ('Open') and a clear resource ('Control Expert project file'), and enumerates the supported file formats. This distinguishes it from sibling tools like new_project and open_remoteconnect_logic without ambiguity.

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

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

The description implies when to use this tool by listing supported file extensions and mentioning that XML formats are imported into a fresh application. However, it does not explicitly state when not to use it or point to alternatives such as new_project for creating projects.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states that the RemoteConnect configuration file is not modified, which is a helpful side-effect disclosure. However, it does not mention potential other side effects, error behavior, return semantics, or whether the operation is read-only or mutating (beyond 'open'). It is incomplete but not misleading.

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

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

Three sentences, each contributing: purpose, usage/prerequisite, and a non-modification note. The information is front-loaded with the core action first. No redundant filler.

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

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

For a tool with one parameter and no output schema, the description covers input requirements and a safety guarantee, but lacks details on expected outcomes (e.g., what 'opening' does in practice, whether it starts a server, or what the function returns). It does not clarify if the operation is blocking, and whether any configuration is automatically applied. Given the sibling context, more context would help an agent know exactly when to use 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?

The only parameter 'path' has zero schema description, but the tool description compensates by specifying accepted file extensions (.PRJ/.RCZ/.STU/.STA) and implying a project file path. This adds meaningful semantics beyond the raw schema, though it does not specify path format, absolute/relative requirements, or validation behavior.

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

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

The description states a specific action ('Open') on a specific resource ('the paired UnitySoControl logic project for a RemoteConnect bundle') and further specifies the accepted file extensions. It clearly distinguishes itself from generic tools like 'open_project' by targeting RemoteConnect bundles.

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 concrete usage guidance: pass a matching .PRJ/.RCZ/.STU/.STA path, and notes a prerequisite (configure SCADAPack OEM context before starting the server). However, it lacks explicit comparisons to sibling tools (e.g., when to use open_remoteconnect_logic vs inspect_remoteconnect_project or build_remoteconnect_logic_copy), leaving the choice somewhat inferential.

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?

Since no annotations are provided, the description must carry the full behavioral burden. It discloses key internal behavior: reads the DFB's pin interface, places the block with computed height (max(in,out)+1), wires one boolean input to the rail, and auto-declares bindings with the right types. This gives significant insight into what the tool does beyond the schema, enough to predict side effects like variable creation.

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 clear purpose in the first sentence, a rationale paragraph, then per-parameter explanations, followed by usage notes. Each sentence adds value; there is no fluff. It is somewhat long but appropriate for the tool's complexity. The key information is front-loaded, and the parameter list is organized with examples.

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 of this complexity (8 parameters, no output schema, no annotations), the description covers the main mechanics and defaults, but leaves important gaps. The 'section' parameter is required yet unexplained, and 'task' and 'pos_x' are only mentioned by default values. It also doesn't describe return values or error scenarios. The description is sufficient for a rough understanding but not fully complete for correct invocation without additional inference.

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

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

Schema description coverage is 0%, so the description must document all parameters. It explains fb_type, instance_name, bindings, rung_input, and rung_contact with examples, covering 5 of 8 parameters. However, it omits explanations for section (required), task, and pos_x, leaving them ambiguous. The agent has to infer their meaning from names and defaults, which is insufficient given the lack of schema descriptions.

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

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

The description starts with a clear, specific verb and resource: 'Place a function block in LADDER from scratch'. It explicitly differentiates from alternative authoring by stating 'NO template needed' and 'For elementary EFBs (TON/CTU/…) author in FBD instead', which implies this tool is for project DFBs. This gives the agent a precise understanding of what the tool does and how it differs from related tools.

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

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

The description provides explicit when-not-to-use guidance: 'For elementary EFBs (TON/CTU/…) author in FBD instead.' It also says 'Then build_project to confirm,' indicating a follow-up step. However, it doesn't explicitly compare with the sibling 'use_fb_in_ladder', though the 'from scratch — NO template needed' phrase implicitly contrasts it. This is clear enough for an agent to decide when to invoke 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?

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses the source location, the effect of latest and max_files, and the shape of the return value including per-object changes, warnings, errors, source references, counts, and ok=false on errors. This is far beyond a minimal statement and gives an agent a solid model of what will happen.

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. The first sentence states the tool's purpose, the second explains the default behavior, the third covers the key option, and the fourth summarizes the return content. Every sentence earns its place with no filler or repetition.

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

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

For a read-only tool with three optional parameters and no output schema, the description covers all essential operational context: default source, parameter behavior, return contents, and error signaling. The absence of annotations is mitigated by the description's own safety signal ('Read') and return details. Nothing critical is missing for an agent to invoke and interpret the result correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the bare parameter definitions. It does so completely: log_path is explained via the no-log_path default, latest is explained as controlling whether to read only the newest log or aggregate, and max_files is explained as the aggregation limit. Every parameter's semantics are addressed 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 and resource: 'Read structured RemoteConnect Object Bulk Edit feedback.' This clearly distinguishes the tool from siblings like inspect_remoteconnect_bulk_edit_workbook, which targets the workbook itself, and create_remoteconnect_bulk_edit_copy, which creates a copy. The scope is unambiguous.

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

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

The description gives concrete guidance on how to invoke the tool: without log_path it reads the newest log, and setting latest=false aggregates up to max_files. This effectively explains the main behavior and configuration options. It does not explicitly name alternatives or state when not to use this tool, but the usage context is clear enough for an agent to select it appropriately.

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?

No annotations are provided, so the description carries the full burden. It clearly implies a read-only operation and describes the return payload (XML). However, it does not explicitly state that it has no side effects or mention prerequisites like an open project, which would be valuable 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 exactly two sentences with no waste. The purpose is front-loaded ('Read the logic of a program section as Control Expert XML'), and the additional detail about XML contents and compatibility adds value without 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?

For a tool with two required, undocumented parameters, the description is incomplete. It does mention the output format, but it fails to explain the parameters themselves, any prerequisites (e.g., open project), or potential error conditions. This makes it insufficient for an agent to confidently invoke it correctly.

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

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

Schema coverage is 0% – neither 'task' nor 'section' has a description. The tool description does not explain what these parameters represent, their expected formats, or valid values. This leaves the agent without guidance on how to fill the two required fields, a significant gap.

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

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

The description states a specific verb (read), a resource (program section), and the output format (Control Expert XML). It explicitly mentions the XML contains ST text, ladder rungs, and FBD networks, which clearly differentiates it from project-wide export or write tools like export_xml or write_st_logic.

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 implies when to use it (to retrieve a single section's logic) by specifying the section as the target. The mention that the format matches import_xml(kind='section') suggests a read-modify-write workflow, but it does not explicitly contrast with alternatives like export_xml or read the entire project structure.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'remove', implying a destructive operation, but does not describe consequences, reversibility, or side effects on related hardware configurations. For a removal tool, this is a significant gap.

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 extremely concise, a single sentence with no wasted words. However, it omits essential context about parameters and behavior, making it under-specified rather than efficiently complete. It could be expanded with meaningful detail without losing conciseness.

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 4 parameters with 0% schema coverage and no output schema, the description is far from complete. It does not clarify the addressing model (bus, drop, rack, slot) or any prerequisites for removal. An agent would struggle to call this tool correctly with only this description.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameters. It references 'rack slot' but does not explain the 'bus', 'drop', or 'rack' parameters, which are likely necessary to locate the exact module. The description adds minimal meaning beyond the raw schema.

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

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

The description clearly states the verb 'remove' and the resource 'module at a rack slot', providing a specific action. However, it does not distinguish this tool from sibling tools like replace_io_module or add_io_module, which also operate on modules at rack slots.

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

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

No guidance is provided on when to use this tool versus alternatives such as replace_io_module or add_io_module. There is no mention of conditions, prerequisites, or exclusions, leaving the agent to guess the appropriate 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?

With no annotations, the description carries the burden of behavioral disclosure. It discloses the critical constraint that the old part number/version must match exactly and references get_hardware for validation, but it does not describe potential side effects, whether the old module is permanently removed, or any prerequisites beyond matching. This is partial transparency for a mutation tool.

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

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

The description is concise (two sentences) and front-loaded with the action and key constraint. The example adds clarity without verbosity, and there is no redundant or filler content.

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

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

The tool is moderately complex with 8 parameters and no annotations or output schema. The description does not cover the addressing parameters (bus, drop, rack) or explicitly state when to use this over add/remove, nor any consequences of the replacement. An agent would struggle to correctly supply all parameters without additional guidance.

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

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

Schema coverage is 0%, so the description must compensate for all 8 parameters. It only explains the old/new part number and version matching, but does not clarify the meaning or usage of bus, drop, rack, or slot beyond their names. The addressing parameters are left ambiguous, which is insufficient given the lack of schema descriptions.

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

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

The description clearly states the verb (replace) and the resource (module), and specifies it is done 'in place (keeps the slot)', which distinguishes it from add_io_module and remove_io_module. The concrete example of swapping a default power supply reinforces the 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 implies when to use this tool through 'keeps the slot' and the example, but it does not explicitly name alternatives or state when not to use it. There is no mention of add_io_module or remove_io_module, so the agent must infer the selection logic from 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?

No annotations are provided, so the description carries the full burden. It does disclose the key behavior — modules are kept only where the new rack has the same slots — which is valuable. But it leaves the fate of modules in non-matching slots, error behavior for mismatched part numbers, and the destructive nature of the operation undisclosed for what is a hardware-mutation tool.

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

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

Two sentences with no filler, so it is efficient. However, the example uses an unpolished arrow notation ('...0800 new_project creates -> BME XBP 0400') that is slightly cryptic and could be clearer.

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 7-parameter hardware tool with zero schema descriptions, no annotations, and no output schema, this description is thin. Addressing semantics (bus/drop/rack), version formats, and error conditions are all undefined, meaning an agent would struggle to invoke 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 0%, so the description must compensate for all 7 parameters. It only hints at part-number semantics through the example; bus, drop, rack, and both version parameters are entirely unexplained. The agent would have to guess how addressing and versioning work.

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

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

The description states a specific verb and resource ('Replace a rack in place') and reinforces it with a concrete example (BME XBP 0800 -> BME XBP 0400). This cleanly distinguishes it from sibling tools like add_rack and replace_io_module, which do different things.

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

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

The phrase 'in place' and the example imply this tool is for upgrading/resizing an existing rack rather than adding a new one, which loosely differentiates it from add_rack. However, there is no explicit when-to-use guidance, no named alternatives, and no exclusion 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?

With no annotations, the description carries the full burden of behavioral disclosure. It explains the behavior of the optional path parameter, including first-save handling, copy creation, and in-place saving. It could further mention overwriting or failure states if no project is open, but the core 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?

One sentence with no filler. Each clause delivers necessary information: the action, the path format, the two scenarios for providing a path, and the behavior when empty. It is front-loaded and 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?

Given the tool's simplicity, one optional parameter, no output schema, and no annotations, the description covers everything needed to invoke it correctly: how to save, copy, and save in place. Additional details like return values are unnecessary for a save operation.

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

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

Schema coverage is 0% and the schema only provides a default value. The description fully compensates by explaining that path must end in .stu, when it should be provided, and what leaving it empty does. This is complete parameter semantics for the single argument.

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

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

The description states the exact verb and resource: 'Save the open project.' It further clarifies three distinct scenarios: first save, saving a copy under a new name, and saving in place. This is specific enough to distinguish the tool from siblings like export_project or close_project.

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?

Clear usage guidance is provided for when to pass a path versus leaving it empty, including the required .stu extension. The description does not explicitly compare against alternatives or state when not to use it, but the context is clear enough for a simple save operation.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It warns about the 'IP Address and Gateway address are not in the same domain' build error, and discloses that setting gateway/subnet rewrites the project archive, reloads it, and marks it unsaved (requiring build_project and save_project). This goes beyond what's in the schema and provides critical side-effect information.

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

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

The description is a single paragraph but well-structured: it starts with the primary purpose, then details address formats, optional parameters with a warning, and side effects. It is compact yet information-dense, with no filler. The only minor inefficiency is the parenthetical example, which is helpful but could be trimmed.

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

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

Given no output schema and no annotations, the description covers the essential side effects (archive rewrite, unsaved state) and the warning condition. It does not mention repo/return value, nor whether setting only address also requires a save, and leaves the 'name' parameter unresolved. Still, it is largely complete for a setter operation.

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

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

Schema coverage is 0%, so the description must compensate. It explains 'address' as IP or node number, and clarifies constraints for 'gateway' (same domain) and 'subnet' (part of addressing). However, it omits the required 'name' parameter entirely and does not specify the format for 'subnet' (e.g., '255.255.255.0'), leaving ambiguity for a required field.

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

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

The description states the specific verb 'Set' and the resource 'a slave DTM's bus address', and distinguishes between IP address vs node number based on protocol. This clearly separates it from sibling tools like set_dtm_dataset or set_dtm_control_parameters, which handle different aspects of a DTM.

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 implicitly defines when to use (to set address, optionally gateway/subnet) and provides context for the gateway/subnet behavior (must be same IP domain). However, it does not explicitly say when NOT to use it or compare to alternatives, leaving some routing to the agent's judgment.

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

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

With no annotations provided, the description carries the full burden. It discloses the build=True behavior (rebuilds DTM→PLC control information) but does not mention other side effects such as overwriting existing parameters, required permissions, or reversibility. The 'read first' hint implies overwriting, but this is not stated explicitly.

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

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

Two sentences, front-loaded with the core action, and includes a critical reference to the read counterpart. No redundant words; every clause adds 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 write tool with no output schema, the description supplies the essential workflow (read first, mirror schema) and the build option's effect. It omits details like error handling, behavior when build=False, and the exact XML structure, but the directive to mirror the schema provides a path to accuracy. Overall, it is sufficiently complete for an agent to invoke 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?

Given 0% schema description coverage, the description must compensate. It adds meaning for 'xml' by describing its content (scanner sizing and %MW mapping) and for 'build' by explaining its effect. It does not explain 'name', though its role as a DTM identifier is inferable from context. Coverage is partial, justifying a moderate score.

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 action: 'Write a master DTM's control parameters' with a specific resource (CetControlParameterInput XML) and specifies the content domain (scanner sizing and %MW mapping). It also differentiates from the sibling get_dtm_control_parameters by the verb 'Write' vs 'Read', making 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?

Explicitly instructs to 'Read the current values with get_dtm_control_parameters first and mirror the schema', providing a clear precondition and workflow. It does not, however, contrast with other write siblings like set_master_dtm_dataset or set_dtm_dataset, so the guidance is partial.

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

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

With no annotations provided, the description must carry the full behavioral disclosure. It states the action 'Import', which implies a write operation, but does not describe side effects like overwriting existing data, validation requirements, or persistence. It is basic but not misleading.

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

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

The description is a single sentence that is concise and front-loaded with the primary action and resource. There is no superfluous content.

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

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

Given no output schema, no annotations, and zero parameter documentation, the description lacks essential details about the xml format, how the dataset is applied, and any confirmation or error behavior. An agent cannot fully anticipate the tool's requirements without additional information.

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 0% description coverage for the two required parameters (name and xml). The description does not explain what each parameter represents or the expected format, leaving the agent to infer that 'name' is an identifier and 'xml' is the dataset content. This is a significant gap.

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

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

The description clearly states the verb 'Import' and the resource 'slave DTM configuration dataset', and explicitly references the export counterpart, distinguishing it from get_dtm_dataset and set_master_dtm_dataset. An agent can immediately understand the primary function.

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 indicates that the tool is used to import a dataset 'previously exported with get_dtm_dataset, possibly modified', which provides clear context on when to use it. It does not explicitly state when not to use it, but the pairing with its export sibling is sufficient.

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?

There are no annotations, so the description carries the full burden. It discloses significant side effects: the project is reloaded, left UNSAVED, must be validated with build_project, and the result appears in get_dtm_control_parameters. It also gives detailed Modbus rules. It does not mention permission requirements or potential data-loss implications of the reload, 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 long, but the length is justified by the exact XML template and validation rules needed for a correct call. The first sentence front-loads the core purpose, and the rest is structured guidance followed by post-call steps. It could be slightly tighter but is appropriately detailed.

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 provides strong operational context, workflow steps, and Modbus-specific rules, but it omits parameter mapping and never clarifies the role of dtm. Given the complexity and the absence of an output schema, this leaves a meaningful gap for correct invocation.

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

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

Schema coverage is 0%, and the description never explains what the dtm parameter is or explicitly maps the xml parameter to the provided XML template. The detailed node shape gives content-level guidance, but the agent is left to infer that xml carries the modified dataset and what dtm means.

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

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

The description opens with a precise action: 'Write back a modified master DTM dataset (adds/edits Modbus scan lines) and reload the project'. This names the specific resource and operation, and the master DTM scope distinguishes it from the sibling set_dtm_dataset. The Modbus scan-line focus makes selection 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?

Clear context is provided: use this when adding/editing Modbus scan requests and then validating via build_project. However, it never explicitly contrasts with set_dtm_dataset or states when not to use this tool, so the guidance stops short of full alternative routing.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the mutation but does not mention overwrite behavior, validation, prerequisites, persistence, or side effects.

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

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

The description is a single clear, front-loaded sentence with no filler. It is efficient, though it sacrifices useful context because it is so short.

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 four required parameters, no annotations, no output schema, and no parameter descriptions, one sentence is insufficient for reliable invocation. Key details about network identification, address formats, and side effects 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?

Schema description coverage is 0%, and the description adds no parameter-level meaning. The format of ip_address, subnet_mask, and gateway, as well as what 'name' refers to, is left entirely to inference.

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

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

The description clearly states the action and target: setting the static IP configuration of a logical Ethernet network. The phrase 'logical Ethernet network' helps differentiate from related networking tools, though it does not explicitly name any sibling.

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

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

There is no guidance about when to use this tool versus alternatives such as configure_cpu_ethernet or set_dtm_address. No prerequisites, exclusions, or context are given beyond the basic action.

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?

No annotations are provided, so the description carries the full burden. It clearly discloses that the project is reloaded from a patched archive and left unsaved, warns about the side effect, and explains the consequence of a specific setting. This is strong behavioral disclosure for a mutating tool.

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

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

The description is compact and front-loaded with the purpose, followed by useful examples and the critical unsaved-state warning. Every sentence adds practical value with no filler.

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

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

For a tool with one open-ended parameter and no output schema, the description covers what settings look like, how values are typed, and the required follow-up sequence. An agent has enough context to invoke it correctly and understand the consequences.

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

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

Schema coverage is 0% and the settings object is open-ended, so the description must compensate. It does so with common idents, value type information ('strings', '0'/'1' for booleans), and one concrete semantic example. It is not exhaustive, but this is reasonable for an additionalProperties map.

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 action, 'Set one or more project settings', with the resource domain clearly identified as build/language options. It provides concrete setting idents, making it unmistakably distinct from the sibling get_project_setting.

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

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

Provides clear operational context: one or more settings can be set, values are strings, and the project becomes unsaved, requiring build_project and save_project afterward. However, it does not explicitly mention when to prefer alternatives like get_project_setting or state exclusions.

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