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

With no annotations, the description carries the full burden, and it delivers useful behavior details: conventions are inferred from existing symbols rather than documentation, and each rule includes evidence and confidence. This sets correct expectations about the output's nature and quality without contradicting any structured metadata.

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

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

The description is well structured and front-loaded: it states the action, gives the critical usage instruction, explains why the tool exists, lists the covered conventions, and documents the argument. Every sentence adds value, and the formatting makes it easy to scan.

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

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

For a simple one-parameter tool with an output schema present, the description is complete. It covers what the tool does, when to call it, what kind of results to expect (evidence + confidence), which areas it covers, and what the path argument means. Nothing needed for invocation 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 schema has 0% description coverage, but the description compensates by explaining the sole parameter: 'path: Project file or directory.' This adds meaning that a bare 'path' string would not convey. It could go further with path type details, but for one parameter it is adequate.

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: 'Report the coding conventions this project already follows.' It then enumerates concrete covered topics (variable prefixes, instance naming, documentation habits) that clearly distinguish it from sibling tools like get_fb_signature, get_tasks, or get_types.

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

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

The description gives explicit when-to-use guidance: 'Call this before generating code.' It also explains why it is necessary, that conventions are only visible in existing symbols and not written down. It does not explicitly state when not to use it or name an alternative, but the intended context is clear.

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

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

With no annotations, the description carries full responsibility, and it delivers substantial behavioral detail. It explains that the project and firmware library reference are combined, that pins absent from the project are still listed, and that 'unsupportedPins' identifies parameters that exist but do nothing on this firmware. This gives an agent important expectations 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 longer than necessary but well organized with a front-loaded purpose, bulleted explanation of the two authorities, and a clear Args section. The detail about unsupportedPins earns its place, and the structure makes the extra length digestible.

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 output schema exists and the tool has only two parameters, the description covers what an agent needs: purpose, parameter meanings, the two information sources, and special behavior around unsupported pins. There are no annotations to fill gaps, but the description is thorough enough on its own.

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 only declares two string parameters with 0% description coverage, so the description must compensate. It adds meaningful semantics: path is a project file or directory, and fb_name is a function block name with concrete examples like 'MC_Power' and 'Y_CamIn'. This is sufficient for the two simple parameters, though slightly more format guidance could push it higher.

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 specific verb and resource: 'Get a function block's interface — for calling or instancing it correctly.' This clearly distinguishes it from sibling tools that retrieve source code, types, or project structure, and it explains the practical reason the interface is needed.

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: use this tool when you need the exact interface of a function block to call or instance it, combining project metadata with firmware library knowledge. It does not explicitly name sibling alternatives or state when not to use them, but the stated use case is strong enough to guide selection.

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

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

With no annotations, the description carries the behavioral burden. It does state the operation is 'List' and explains the conceptual mapping to AT %I/%Q variables, which is useful context. However, it does not disclose whether the project must already be loaded, whether the path can be a directory with a specific structure, or any error/edge-case 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 compact and front-loaded. The first sentence states the core action, the second adds valuable domain context, and the Args line documents the only parameter. Every sentence 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?

Given the tool has a single parameter and an output schema, the description is largely sufficient. It explains what the tool returns conceptually and documents the path argument. The main gaps are the lack of usage guidance versus sibling tools and implicit prerequisites, but these are minor for a simple listing 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 does add meaning by defining 'path' as 'Project file or directory,' which goes beyond the bare string type in the schema. However, it does not explain expected file extensions, directory layout, or whether the path is resolved relative to the current workspace.

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: 'List the controller and network I/O configuration.' It clearly distinguishes this from sibling tools like get_tasks or get_motion_config by naming the exact subject matter, and the added explanation about I/O groups, address ranges, and drivers makes the purpose concrete.

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 about when to use this tool versus alternatives such as get_motion_config or get_tags. The description implies a read-only listing operation, but it never states prerequisites, exclusions, or how to choose between this and related configuration 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, the description carries the full burden of behavioral disclosure. It explains what the tool reports (availability and how to enable) and the implication of unavailability (fallback to observed usage). It does not mention side effects, but as a status report, it is likely read-only. The description adds value beyond a simple status check by explaining the dependency chain.

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 well-structured. It opens with a direct statement of purpose, then provides essential context in a second paragraph. Every sentence contributes meaning, 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 zero-parameter tool with an output schema present, the description is complete. It explains what the tool reports and why the status matters, giving an agent sufficient context to decide when to call it. No missing information is evident 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, and the schema is empty with 100% coverage (since there are no properties). The description does not need to elaborate on parameters. Per the baseline for zero parameters, a score of 4 is appropriate.

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

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

The description clearly states the tool's function: 'Report whether the firmware library reference is available, and how to enable it.' It identifies a specific resource (firmware library reference) and the action (report availability and enablement). This distinguishes it from sibling tools like get_type or get_fb_signature, which retrieve specific data objects.

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 context on why this tool matters: it explains that the reference is vendor help installed with MotionWorks and that unavailability causes library signatures to fall back to observed usage. This implies the tool is useful for diagnosing signature quality, though it does not explicitly name alternatives or state when not to use it. It gives clear situational guidance without 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 disclosure burden. It explains the internal behavior—joining AxisNum assignments in startup code with servo groups in the I/O configuration—rather than merely restating the tool name. The 'summarise' wording also implies a read-only operation, though it does not explicitly state side-effect status.

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 front-loads the purpose, gives a focused domain explanation with a concrete example, and ends with the argument. No sentences are wasted, and the code example earns its place by clarifying how AxisNum bindings work.

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-required-parameter tool with an output schema, the description covers input semantics, purpose, and the question it answers. It does not mention prerequisites like a loaded project, but the path argument and output schema make the tool callable without much 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 only says path is a string with no description, so the description's 'Project file or directory' adds essential meaning. This adequately clarifies what the agent should pass for the single required 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 opens with a specific verb and resource: 'Summarise the motion setup' and names the exact content covered (axes, amplifier bindings, network nodes). It also distinguishes itself by explaining that it joins AxisNum assignments with servo groups, setting it apart from generic I/O config tools.

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

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

The description gives a concrete use case: answering 'which servo is axis 1?', which makes the intended invocation clear. It does not explicitly list alternative tools or exclusion cases, but it provides enough context to select this tool over simpler retrieval 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, the description carries the full burden, and it delivers: it discloses exact return behavior for Structured Text (original source, tab alignment, inline comments), the compact text-plus-nets representation for Ladder/FBD, paging via body.truncated and offset, and output-size tradeoffs relative to raw XML. This is far richer than a generic 'Get one POU.'

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 adds high-value behavioral details, then lists parameters in an Args block. Every sentence contributes: source fidelity, network representation, paging, and param semantics. It is long but dense and well-organized, not padded.

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

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

Given the tool's complexity, an output schema exists, and the description covers behavior, paging, param meanings, and the relationship to get_pous, the definition is complete for an agent to select and invoke the tool correctly. No critical operational detail appears to be 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%, so the description must explain all parameters, and it does: path as project file or directory, pou_name as exact name from get_pous, offset as line paging, include_interface as per-scope variables, and include_outputs as graphical block output pins. This adds real meaning beyond the bare schema types.

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: 'Get one POU: its interface, its body, and every network it contains.' It clearly distinguishes this from the plural sibling get_pous by emphasizing a single POU, and it names concrete content areas rather than merely restating the tool name.

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 'This is the workhorse tool' implies broad/default usage, and the instruction that pou_name must be 'exactly as reported by get_pous' hints at a prior step. However, there is no explicit guidance about when to prefer this tool over get_routine, render_pou_source, or validate_pou, nor any when-not-to-use conditions.

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

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

No annotations are provided, so the description must disclose behavioral traits. It states 'List' which implies a read-only operation, but does not mention whether it requires an open project, works directly on files, or has any side effects. It also does not describe what happens if the path is invalid or if search yields no results. The description does not contradict anything, but it is insufficiently 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: one line stating purpose, then a clean Arg list with each parameter explained. No unnecessary words; the purpose is front-loaded and the argument details are structured and scannable. This is an ideal format for agent consumption.

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?

All four parameters are explained and an output schema exists, so return values are covered. However, the description lacks some operational details: it does not state whether it scans subdirectories, handles relative vs absolute paths, or what the size field represents. Given the read-only nature and clear purpose, it is mostly complete, but a few behavioral nuances 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 coverage is 0%, so the description must fully explain parameters. It does so effectively: path is explained as project file or directory, language lists allowed values ('ST', 'LD', 'FBD'), task gives an example ('FastTsk'), and search specifies case-insensitive substring on POU name. This adds substantial meaning beyond the schema's type/default info.

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 lists programs and function blocks, with specific output fields (language, task, size). It distinguishes from siblings like get_pou (singular) and get_udts by specifying the resource and scope, so an agent can select it appropriately.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention that get_pou fetches a single POU or that get_routines handles routines, nor does it state any exclusions or conditions. The usage context must be inferred solely from the name and purpose.

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 discloses that routine_name is ignored, which is a behavioral trait. It also implies identical behavior to get_pou. However, it does not specify output format, side effects, or permissions. The alias reference partially compensates, but the lack of detail on what 'body' means or any error conditions leaves a moderate 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 compact docstring with a one-line purpose and an Args list. It front-loads the primary purpose and then provides parameter details without any fluff. Every sentence adds value, and the structure is easy to parse.

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

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

Given the simplicity of the tool (an alias with 3 parameters) and the presence of an output schema (not shown but indicated), the description is sufficient. It explains the alias, the ignored parameter, and all parameter semantics. The only missing piece is a description of the return value, but the output schema likely covers that, so it is not a critical gap.

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

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

Schema description coverage is 0%, so the description must explain all parameters. It does: path is the project file or directory, program is the POU name, and routine_name is explicitly ignored. This fully compensates for the schema's lack of descriptions and is clear and precise for an agent.

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 ('Get'), resource ('POU's body'), and clarifies it is an alias for get_pou. It distinguishes from siblings by naming the canonical tool and explaining the studio5000 familiarity rationale. This is unambiguous and leaves no doubt about what the 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 explicitly says it is an alias for get_pou and explains the routine_name parameter is ignored to support the studio5000 calling convention. This gives clear guidance on when to use this tool (when familiar with studio5000 naming) and implicitly that get_pou is the canonical alternative. It does not provide explicit exclusions, but the alias relationship itself is strong 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, the description carries the full burden. It says 'List', implying a read-only operation, but does not disclose any other behaviors such as output format, pagination, error conditions, or performance characteristics. It is too minimal to inform the agent of important behavioral traits.

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 very short and front-loaded with the primary action. It efficiently states the purpose and then lists arguments without fluff. It is well-structured for a simple tool.

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

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

For a simple listing tool with an output schema, the description covers the essential action and parameters. However, it omits any context about return value structure, usage scenarios, or constraints beyond the basic filter. It is adequate but not thorough.

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 brief meanings for both parameters: 'path' as project file or directory, and 'program' as filter by POU name. This adds value beyond the schema's bare types, but lacks detail on expected formats or edge cases.

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 'List POUs', specifying the action and resource. It also explicitly mentions it's an alias for get_pous, which clarifies its relationship to a sibling, even though it doesn't differentiate from that sibling. The purpose is unambiguous.

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

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

No explicit guidance on when to use this tool versus alternatives. It only states it's an alias for get_pous, which implies interchangeability but doesn't provide conditions for selection or mention when not to use it. Sibling tools like get_pou or get_routine are not addressed.

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 for behavioral disclosure. It reveals a non-obvious behavior: missing sources trigger an 'exportGuidance' block with steps from MotionWorks' help. It also describes the tool's diagnostic output (readability, contributions, disagreements). It does not explicitly label the operation as read-only, but 'Report' and 'inspect' imply it; the description still adds meaningful 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 compact and well-structured: a one-sentence purpose, a usage guideline, an edge-case behavior note, and an Args line. Every sentence earns its place, and the most important information (purpose and when to use) is front-loaded before technical details.

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

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

Given the tool has only one parameter and an existing output schema (so return values need not be described), the description covers all necessary context: what it reports, when to use it, and how it handles missing sources. The common native-project-without-export case is explicitly addressed, making the tool fully self-explanatory.

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 fully explain the parameter, and it does: 'path: File or directory to inspect.' This adds semantic meaning about both the type and expected usage, going beyond the bare schema property name. For a single-parameter tool, this is 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 opens with a specific verb and resource: 'Report which export forms exist for a project and what each contributes.' This clearly distinguishes it from sibling getters (get_udt, get_routine, get_tags, etc.), which target different entities. The agent can immediately understand the tool's unique function without inspecting 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?

The description provides an explicit trigger: 'Use this when a tool returns less than you expected.' It also explains what the tool returns in that context (readable sources, contributions, disagreements). However, it does not explicitly state when not to use it or name alternative tools, so it stops short of full exclusion guidance.

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

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

With no annotations, the description carries the behavioral burden and does disclose the core behavior: it returns the declaration and all reference locations. The verb 'Get' and 'returns' imply read-only operation, though it does not explicitly state that it makes no modifications or mention error behavior. This is fairly transparent for a simple lookup 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: the first sentence states the tool's purpose, the second gives a use case and output details, and then an args list adds parameter semantics. Every sentence contributes 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?

Given the simple two-parameter schema and an output schema that covers return shape, the description is largely complete. It explains the tool's purpose, when to use it, and both arguments. It does not mention prerequisites like project loading or error cases when a tag is not found, which are minor gaps.

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

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

Schema coverage is 0%, so the description must compensate. It adds meaning to both parameters: path is described as a project file or directory, and tag_name is described as a variable name with a qualified-name example. This gives the agent practical guidance beyond the bare schema types.

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 gets a single variable's full detail plus all its usages, naming the concrete output: declaration with address and comment, and every POU, net and line referencing it. This distinguishes it from sibling tools like get_tags and get_type by emphasizing the per-variable detail and usage traversal.

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 an explicit use case: 'Use this to answer "what is this signal and what drives it?"' and describes what it returns, giving the agent clear when-to-use guidance. It does not explicitly mention when-not-to-use or name alternative sibling tools, so it stops short of full differentiation.

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 explains that the tool combines global and POU variables and that global variables carry AT addresses, which is useful. However, it does not explicitly state read-only behavior, potential side effects, or any prerequisites (e.g., project must be loaded), though 'List' implies a read 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 concise and well-structured: a one-sentence purpose followed by a clear args list. It front-loads the core purpose and then details parameters without redundant fluff. A minor improvement would be to mention output format, but that is covered by the output schema.

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

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

Given the tool has an output schema and 5 parameters all described with examples, the description is fairly complete. It explains what data is returned (full symbol surface) and how to filter. It does not cover edge cases like empty results, but those are typically not required in the description. Overall, adequate for an agent 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 so excellently by explaining each parameter with concrete examples: 'path: Project file or directory', 'scope: Filter by scope, e.g. VAR_GLOBAL...', etc. This adds meaning well beyond the bare schema and gives the agent exactly 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 clearly states 'List project variables' and elaborates on the specific scope (global variables with AT addresses plus POU interface variables), making the tool's purpose unambiguous. It also distinguishes itself from siblings like get_tag (singular) and other type/UDT tools, so an agent can select it appropriately.

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 the full symbol surface of the project) but does not explicitly mention when not to use it or suggest alternatives (e.g., get_tag for a single variable). The context is clear but lacks direct comparison or 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 provided, the description carries the full burden of behavioral disclosure. It describes the operation as a listing, which implies read-only behavior, but does not explicitly state side-effect-freeness, permissions, or any constraints such as requiring an open project. This is adequate for a read operation but lacks explicit safety confirmation.

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 delivers the core purpose, the second adds valuable execution-order context, and the Args section cleanly documents the parameter. No fluff or redundant phrasing.

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 simple (one parameter) and an output schema exists, so return-value details are not needed. The description covers purpose, parameter meaning, and a practical usage warning. Minor gaps: it doesn't state prerequisites (e.g., whether a project must be loaded) or any path format restrictions, but these are unlikely to impede correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It does: the 'Args' section explicitly defines 'path' as 'Project file or directory,' which adds meaning beyond the bare schema type. This is concise and informative, though it could have specified whether a file or directory is preferred in different scenarios.

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 ('controller tasks'), and adds the attributes of timing and programs each task runs. This clearly distinguishes it from sibling tools like get_pous or get_routines, which deal with code blocks rather than task scheduling.

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 a clear use case: to check task assignment before assuming execution order, and explicitly mentions jitter. While it doesn't name alternative tools or say when not to use it, the guidance is actionable and contextually relevant, giving the agent a reason 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, the description carries the behavioral disclosure burden. It explains that type_name is exact, that empty type_name returns types matching search, and that search is case-insensitive. It does not explicitly state read-only semantics, but 'Get' strongly implies it, and the conditional behavior is well documented.

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, front-loaded with the core purpose, and uses a clearly structured Args block. Every sentence adds useful information; there is no filler or repetition of schema field names without added 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 simple read-style lookup with three parameters and an output schema present, the description covers all necessary calling semantics. It explains parameter defaults, behavior when type_name is empty, and routes to the relevant sibling tool when appropriate.

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

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

Schema description coverage is 0%, so the description must fully compensate. It does: path is defined as 'Project file or directory,' type_name is 'Exact type name' with empty behavior, and search is a 'Case-insensitive substring filter' used only when type_name is empty.

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: 'Get a type definition with its members.' It also explicitly differentiates from the sibling get_fb_signature by stating when that tool should be chosen instead, making the purpose immediately recognizable.

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 names get_fb_signature as the alternative for function-block pin tables in a calling-oriented form, giving the agent clear routing guidance. It also explains the interaction between path, type_name, and search, which defines the tool's calling conditions.

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

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

With no annotations, the description carries the disclosure burden; it adds a meaningful source constraint by stating that Yaskawa motion-library types are only present 'when the PLCopen XML export is present, which it is the only source that carries.' The word 'List' implies read-only behavior, and filter semantics are disclosed, though it does not address failure/edge cases.

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

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

The description is front-loaded with the purpose, then one contextual sentence, then a tight Args list. It is efficient and well structured, though the Yaskawa type-name examples add a little length that could be trimmed without losing the core message.

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 4-parameter listing tool with an output schema, the description covers project scope, source availability, and all filter mechanics. It is complete enough for an agent to call it correctly, but it leaves the relationship to sibling type/library tools implicit.

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

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

Schema description coverage is 0%, but the Args block defines every parameter beyond the schema: path as project file/directory, search as case-insensitive substring, kind with its allowed values, and limit as the maximum return count. This fully compensates for the schema's bare properties/defaults.

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

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

The opening 'List data types, structs and function blocks available in the project' names a specific verb, resource, and scope. It clearly covers a plural, project-scoped inventory, which separates it from singular get_type/get_udt, though it does not explicitly name these 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 phrase 'This is the vocabulary an agent must code against' gives a clear reason to use the tool when selecting type names, and the filters in Args show how to narrow results. There is no explicit when-not guidance or comparison to overlapping siblings such as get_udts, list_library_blocks, or list_fb_catalog.

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 disclose the key behavior: it returns a UDT with its members, or all project-defined types when udt_name is empty. However, it does not mention failure modes, path resolution, or whether the operation is read-only in explicit terms.

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

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

The description is short, front-loaded with the action and resource, and each sentence in the args section adds necessary semantic value. 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 simple two-parameter lookup tool with an output schema present, the description covers invocation semantics well. The main gap is routing guidance among sibling lookup tools, but the core call behavior is adequately 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 does add meaning to both parameters: path is a project file or directory, and udt_name is a type name whose empty value changes the result. This is sufficient but terse.

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 resource ('user-defined type definition') and includes 'with its members' plus the empty-name behavior. It is specific enough to distinguish from plural list-style siblings, though it does not explicitly contrast with get_udts or get_type.

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 choose this tool over get_udts, get_type, or get_types. The empty-string behavior is a parameter detail, not a selection guideline.

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 scoping behavior (project-defined only) but does not describe any side effects, required permissions, error behavior, or return format. For a listing tool, the absence of behavioral details beyond the basic scope is a notable 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, consisting of one main sentence plus a one-line parameter explanation. It front-loads the core purpose and scope with no filler or redundant information, making it easy to parse 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 simple (lists UDTs) and has an output schema (though not shown), so the description does not need to explain return values. However, given no annotations and minimal parameter detail, the description could provide more context on path semantics or usage examples. It is minimally sufficient but leaves room for ambiguity about acceptable path 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 for the path parameter. The description says 'Project file or directory', which adds basic meaning but is vague about file formats or expected path structure. It does not clarify whether the path must be a specific project file type or how directories are handled, providing only minimal semantic value.

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

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

The description states a specific verb ('List') and resource ('user-defined types only'), and explicitly scopes to project-defined UDTs while excluding the vendor library. This clearly differentiates from sibling tools like get_types that likely list all types, so an agent can distinguish it without opening other definitions.

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 it by stating 'only' and 'excluding the vendor library', but it does not explicitly mention alternative tools or conditions for when not to use it. Sibling tools like get_types exist, but no direct comparison or exclusion is provided, leaving the agent to infer usage context.

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

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

No annotations are present, so the description carries the full burden. It reveals that the tool is a read-only listing operation and highlights a unique completeness caveat, but it does not mention prerequisites (e.g., whether a project must be open), performance implications, or possible errors. It adds some behavioral context but stops short of a full disclosure.

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 action and keeps the purpose statement immediate. The explanatory note about the vendor library is valuable context and earns its place. The Args section is clearly separated, making the structure scannable, though the middle paragraph is slightly verbose for an agent.

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

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

With an output schema present and only two simple parameters, the description covers the main usage context well. It explains why this tool is the right choice for project-level block listing and contrasts it with the vendor library. It could be more complete by explicitly contrasting with siblings like get_fb_signature or list_library_blocks, but the given note is sufficient for correct selection.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. It defines 'path' as 'Project file or directory' and 'search' as a 'Case-insensitive substring filter on the block name,' adding practical meaning beyond the bare string types in the schema. Format details are left to the output schema, but the essential semantics are provided.

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: 'List every function block the project uses, with the parameters it passes.' It further distinguishes itself from sibling tools like list_library_blocks by framing this as the project's actual 'practical coding vocabulary' and stating the vendor library is not exported, making this the only complete view for a 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 gives clear context: use it to see the blocks actually available in a project and their formal parameter names, because the vendor library is not exported as type definitions. However, it does not explicitly name alternative tools like list_library_blocks or search_library, nor does it state when not to use this tool, so the guidance is strong but not exhaustive.

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 adds meaningful context beyond the schema by explaining that results may be complete or partial depending on the export source, which directly affects how an agent should interpret the output. It does not explicitly state read-only behavior, but 'Report' strongly implies it.

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

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

Two sentences with no filler. The primary purpose is front-loaded, and the second sentence adds valuable interpretive context without redundancy. 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 zero-parameter reporting tool with an output schema, the description is complete. It states what is reported, the quality dimension, and the key caveat about partial results. It also points to the README for deeper context, which is appropriate.

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

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

The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to add about parameter meanings. The baseline of 4 applies because no parameter documentation is needed.

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 ('Report') and names the exact resource ('which IEC body languages this server can render') plus the added dimension of quality ('and how well'). This clearly distinguishes it from sibling tools like list_library_blocks or get_pous, which address different resources.

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 useful interpretive context but does not explicitly state when to use this tool versus alternatives or when not to use it. The intended use is implied by the unique purpose, but there is no direct guidance about choosing it over 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 carries the full burden. It discloses the behavioral trait of being device documentation independent of project state, but does not mention performance implications or that it might be a large list. It also doesn't discuss return details beyond the output schema, but gives context that it lists all blocks. This is adequate context beyond the basic 'list' action, but not exhaustive.

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 efficient with a clear verb and resource, and the paragraph about device documentation is front-loaded. The Args section is well-structured with each parameter on its own line, but the entire description is somewhat wordy; the purpose and usage could be tightened. Still, each sentence earns its place, so a 4 is appropriate.

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 is a simple read-only listing with an output schema, the description covers purpose, usage guidance, and parameter semantics. The output schema exists, so return details don't need explanation. However, it doesn't explicitly mention that the tool executes quickly or that it is safe, but that is implied by 'device documentation'. Minor gap: doesn't differentiate from list_fb_catalog clearly, but it mentions 'firmware library' which helps. Overall complete for its complexity.

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

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

The schema has no descriptions for the three optional parameters (0% coverage), so the description compensates by explaining each: search as case-insensitive substring on block name, library as filter by library, limit as maximum count. This adds meaning but is largely straightforward from the parameter names. It does not describe the default behavior when parameters are empty, but the schema provides defaults. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists function blocks provided by the MotionWorks firmware library, distinguishing it from project state tools. It explicitly notes it is device documentation, which differentiates it from siblings like list_fb_catalog or search_library, and includes usage context about what it does not include.

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: to find out what is available before writing code, and that it works without opening a project. It contrasts with project state tools and mentions it includes blocks this project never uses, which is critical guidance for the agent to choose this over 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 present, so the description carries the full burden. It discloses that this tool is limited to PLCopen XML only (implied by open_project finding 'Extended and native sources') and that it is kept for parity with a legacy connector. It doesn't mention mutation, but 'Parse and return summary' implies a read-only operation; the limitation and parity context add value beyond a simple one-liner.

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 efficient: a one-sentence purpose, a rationale for parity, and a clear parameter explanation. It front-loads the primary action and avoids fluff. Every sentence earns its place without 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?

Given there is an output schema (true), return values are presumably covered there, so the description need not repeat them. It covers the tool's function, limitation, and parameter semantics. A minor gap is that it doesn't describe what a 'project summary' includes, but that is likely in the output schema, keeping completeness acceptable.

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%, but the description compensates fully by explicitly documenting the parameter in the 'Args:' section: 'plcopen_xml_path: Path to a PLCopen XML file exported from MotionWorks IEC.' This adds specific meaning (file path, export source) far beyond the bare schema type 'string'.

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 ('Parse'), resource (PLCopen XML export), and output ('project summary'). Clearly differentiates from sibling 'open_project' by noting it is 'Kept for parity with the studio5000 connector' and that open_project is preferred, so an agent can distinguish them.

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

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

Explicitly names the alternative (open_project) and gives the condition for preference: 'open_project is preferred because it also finds the Extended and native sources.' This tells the agent when to avoid this tool and why, leaving no ambiguity about 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, the description fully discloses behavioral traits. It explains that exports are merged and divergences are returned, highlighting that divergences are often the most important aspect. For native projects, it states that code lives in a compound binary, so no source, variables, types, or I/O can be read, and it provides exportGuidance with detailed instructions. This is exemplary transparency.

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

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

The description is well-structured with the main purpose front-loaded, followed by essential behavioral details and special-case handling. While longer than some, every paragraph adds critical information for correct invocation and interpretation. It is appropriately sized for a complex entry-point 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 covers what the tool does, what it returns (summary and divergences), how to interpret the divergences, and the special native-project scenario with exportGuidance. Given the complexity and the presence of an output schema, this is complete enough for an agent to use it correctly without further 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?

Despite schema description coverage being 0%, the description thoroughly explains the 'path' parameter by enumerating the three accepted formats (PLCopen XML, Extended IEC export directory, native project directory) and noting that the source is auto-detected. This adds significant meaning beyond the schema's bare 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 clearly states the tool opens a MotionWorks IEC project and merges all export forms. It identifies itself as the entry point for every other tool, distinguishing it from siblings like load_project. The verb, resource, and scope are explicit, and the path type detection is described.

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 it is the entry point for every other tool, giving strong guidance on when to use it. It also explains the accepted path types and the special case for native projects with no export, including how to handle exportGuidance. This is clear, actionable usage guidance.

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

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

With no annotations, the description carries the behavioral disclosure burden. 'Health check — verify the server is running' communicates that this is a non-mutating status probe. It doesn't detail response contents, but the output schema covers that.

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

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

The description is exceptionally lean—five words of substance—and every word adds meaning. The 'Health check' label is front-loaded and the explanatory clause follows directly.

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 parameterless status probe with an output schema, this description is complete. It states the tool's purpose and implied read-only nature; nothing else is required 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?

The tool has zero parameters, so parameter documentation is not needed. The baseline of 4 applies because there is no semantic gap for the description to fill.

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, 'verify,' and a clear resource, 'the server is running.' It also establishes the tool as a health check, which sets it apart from sibling tools like correlate_projects and trace_tag.

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

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

The description clearly implies when to call it: any time the agent needs to confirm the server is up. It doesn't contrast against alternatives, but none of the sibling tools are plausible substitutes for a health check, so no exclusion 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. It discloses the output shape and the uncertainty about IDE import support, which is key behavioral context. It does not mention side effects (e.g., project modifications) or prerequisites (e.g., open project), but for a rendering tool these are likely minor. The limitation is clearly stated, showing transparency.

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 moderately long but each sentence adds value: purpose, structure details, caveat with alternatives, and parameter list. It is front-loaded with the primary purpose and flows logically. Slight improvement could be made with bullet points for parameters, but it remains concise relative to 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?

Given the tool has 6 parameters and an output schema, the description covers the output format, import caveat, and all parameter semantics. It provides enough for an agent to call it correctly, including how to handle the uncertain import path. The output schema itself presumably documents return values, so no omission is significant.

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 lists all six parameters with precise meanings: name, pou_type (with enumerated values), language (with enumerated values), declaration (with clarification about missing END_*), code (body language), and description. This adds substantial 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 states a specific verb ('Emit') and resource ('a POU') with a clear format ('MotionWorks' Extended IEC 61131-2 export'). It also details the output structure (header, declaration blocks, body region), which distinguishes it from render_type_source (for types) and other tools. The purpose is unambiguous.

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

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

It provides context on when the output is appropriate: it matches the IDE's text export, and it explicitly warns that the IDE may not import this format, offering alternatives (paste or wrap in PLCopen XML). However, it does not explicitly state when to use this tool over siblings like render_type_source or list_languages, 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 provided, the description carries the burden of behavioral disclosure. It usefully warns that the output matches IDE exports but the documented import path is PLCopen XML. However, it does not explicitly state whether the operation is read-only, whether it requires a loaded project, or whether there are 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 mostly concise and front-loaded with the purpose. The caveat referencing render_pou_source is relevant and compact. The Args section is clearly formatted and easy to parse, though the caveat might be slightly verbose for the value it adds.

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 leaves ambiguity about whether the tool renders an existing type from the project or creates a new definition from provided members. It also does not mention prerequisites like loading a project, which is a significant gap given the siblings open_project/load_project exist. The optional members parameter further clouds this. The output schema may cover return values, but usage context is incomplete.

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 compensates by explaining each parameter: name is the type name, members is a list of objects with a concrete example, and comment is an optional description stored in the DESCRIPTION region. The example for members adds valuable semantics, though it does not clarify optionality or whether additional fields are allowed.

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

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

The opening sentence states a specific verb ('Emit') and resource ('TYPE ... END_TYPE struct definition') in a clear context ('MotionWorks' text shape'). This clearly distinguishes it from siblings like get_type/get_types, which would return structured data rather than source text.

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 does not explicitly state when to use this tool versus alternatives. The 'Same caveat as render_pou_source' line implies it is the type-focused analog, but it never names get_type/get_types or states when the source text is needed instead of the structured object. Usage is implied but not explicitly routed.

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 discloses what the search covers (names, formal parameters, descriptions, notes, example code, enumerated types) and includes example queries showing breadth. It does not mention side effects (search implies read-only), but that is implicitly safe. It does not discuss performance or limits beyond the 'limit' parameter, which is documented. Overall, it gives a solid behavioral picture.

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 in the first sentence, then a clarifying purpose statement, then a structured 'Args:' section. It is economical, though the enumeration of search fields is repeated (first sentence lists some, second sentence expands), causing slight redundancy. Still, it is compact and scannable.

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 search tool with two simple parameters, the description covers the core behavior, search targets, and parameter meanings. An output schema exists, so return format is presumably defined there. It omits edge-case behavior (case sensitivity, wildcard support, pagination beyond limit), but for a straightforward search tool this is adequate. The example queries add practical context that helps an agent use 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 'query' it provides a type ('Text to look for') and concrete examples ('torque', 'cam in', 'BufferMode', 'alarm'); for 'limit' it says 'Maximum number of matches', clarifying its meaning. Both parameters are covered, though default value (40) is not mentioned in the description (it is in the schema). This adds significant value over the bare 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 ('search') and resource ('firmware library'), enumerates the search fields (block name, pin name, type, description, formal parameters, notes, example code, enumerated types), and explicitly frames the intended use case: 'Answers "which block do I use for X?"'. This clearly distinguishes it from siblings like list_library_blocks (listing all blocks) and search_logic (searching logic contexts).

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

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

The description gives a clear usage context: 'Search the firmware library by block name, pin name, type or description' and the purpose answer for 'which block do I use for X?'. It does not explicitly name alternatives or say when not to use it (e.g., for logic-specific searches, use search_logic), but the context is sufficient for an agent to infer typical use. Lacks explicit 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 it delivers: it discloses the two-phase match ordering (symbol-table entries first, then raw Structured Text lines) and explains the plain-regex-vs-glob gotcha with a concrete example. Minor gaps remain — no explicit read-only statement and no behavior on zero matches — but the non-obvious semantics are genuinely surfaced.

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

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

The purpose is front-loaded in the first sentence, followed by usage context, search-order disclosure, and the regex caveat before a compact Args block. The regex note is slightly verbose and its example is project-specific, but every sentence contributes value and nothing 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?

An output schema exists, so return values need no explanation. The description covers search scope, match ordering, regex semantics, and all parameters — a complete picture for a search tool of this complexity. It would benefit from a read-only safety hint and no-match behavior, but given zero annotations, the description handles the core burden well.

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 fully compensate, and it does. The Args section documents all three parameters with real semantics: path's target type, pattern's accepted forms (tag name, block name, or regex), and limit's meaning (maximum number of matches). The pattern parameter receives especially valuable interpretation guidance.

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 first sentence states a precise action — 'Search for a tag, block or regex across every POU and network' — with a defined scope that distinguishes it from the sibling search_library (which targets libraries, not POUs/networks). The question-answering framing ('where is this used?', 'which routines call this block?') reinforces its specific role in code navigation.

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

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

The description gives clear usage context by posing the exact questions it resolves ('where is this used?' and 'which routines call this block?'), which tells an agent when to reach for it. However, it never names alternatives or states exclusions, so an agent facing siblings like search_library or get_tag must infer the boundary from scope wording rather than being routed explicitly.

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 behavioral burden. It discloses that validation checks non-existent tags, undefined types, unavailable function blocks, and incorrect formal parameter names, and that declared_vars suppresses false positives for local symbols. It does not state whether the operation is read-only or requires an open project, but the 'validate' phrasing implies no mutation.

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

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

Front-loaded purpose, then usage guidance, then a compact Args list. Every sentence earns its place, with no repetition of schema defaults or boilerplate. The formatting is scannable for an agent.

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 core input semantics and the scenarios it handles. Since an output schema exists, return-value explanation is not required. It omits explicit mention that a project must be open/loaded before validation, but 'against the project's real symbols' implies that dependency. Minor gap only.

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%, but the description's Args section fully compensates: it explains the meaning and constraints of every parameter, including that code must contain no declaration blocks, declared_vars prevents false undeclared errors, and pou_name is only for labeling. This is strong added value beyond the bare schema.

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

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

Description opens with a specific verb+resource: 'Validate agent-written IEC code against the project's real symbols.' It clearly identifies what the tool does and distinguishes it from sibling read/list/search/render tools by focusing on validation of generated code.

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 tells the agent when to use it: 'Call this on generated code *before* handing it to a user.' It also explains what kinds of LLM mistakes it catches, which clarifies the intended scenario. It does not mention exclusions or alternatives, but the usage context is clear.

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