mz_dfs_info

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

With no annotations, the description must carry the behavioral burden; the explicit verb '读取' does signal a read-only operation and the format list explains which backends are used. It does not mention errors on unsupported files, file-size performance, or what happens when metadata is unavailable, leaving some behavioral uncertainty.

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

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

The description front-loads the purpose in a single sentence and then gives only the supporting format and argument details. Every sentence adds information and there is no filler.

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

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

For a one-parameter metadata reader with no output schema, the description covers the expected return facets (type, item names/units, time axis, grid size), accepted file families, and the required absolute path. It could be more complete by noting failure behavior on invalid paths or unsupported files, but nothing essential is missing for normal use.

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

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

Although schema description coverage is 0%, the Args section supplies 'path: 结果文件绝对路径', adding the crucial requirement that the path be absolute, which the bare schema ('Path') omits. The supported-format list in the main description also constrains what path should point to.

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 '读取结果文件元信息' and then enumerates exactly what is returned: 类型、条目名称/单位、时间轴、网格规模. This clearly distinguishes it from siblings mz_dfs_read and mz_dfs_plot by scoping it to metadata retrieval rather than data reading or plotting.

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 tells the agent which file families are supported (.dfs0/.dfs1/.dfs2/.dfs3/.dfsu and .res1d/.res11), so suitable inputs are clear. However, it does not explicitly state when to prefer this over mz_dfs_read or mz_dfs_plot, nor any when-not conditions; the routing is only implied by the word 'info' and the file-type list.

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