ads_dump

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

With readOnlyHint=true already covering the safety profile for the PLC side, the description adds the meaningful behavioral detail that this operation also writes files to disk and returns counts, file paths, and a 50-leaf preview rather than the full data. It does not explain what out_dir defaults to, whether existing files are overwritten, or what max_leaves / max_total_mb do when hit.

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

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

Front-loaded with the core action and scope, then constraints, then return shape and hand-off to sibling tooling. Dense but every sentence carries information; the parenthetical expansions are the only slightly heavy part.

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 bulk-dump tool that also writes files, the description covers scope, filtering, exclusions, and return shape well, and an output schema exists so return values need not be detailed. However, with 0% param coverage and no statement about write destination defaults or cap behavior, the agent cannot fully predict the side effects of the call.

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 carry all five parameters. It explains pattern with syntax examples and include_system with its default behavior, but out_dir, max_leaves, and max_total_mb — two of which look like truncation/safety caps an agent should reason about — are entirely undocumented.

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 ('Read EVERY variable on the PLC'), the exact scope (top-level symbols fully expanded through the datatype table including structs, FB instances, arrays of structs), and the two artifacts produced (nested JSON tree plus flat CSV). This clearly separates it from siblings like ads_read, ads_read_many, and ads_list_symbols.

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

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

Gives concrete scoping conditions ('pattern limits the roots (MAIN.*, GVL_*)', 'system/library symbols excluded unless include_system') and routes the agent to direct alternatives for detail ('use proj_read_file / rec-style tooling on the files'). It doesn't explicitly contrast against ads_read_many or state when a bulk dump is preferable to a targeted read, but the context is strong.

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