partvtk

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 does reveal the output destination (savevtk default), the filtering behavior (onlytype default fluid only), and the write intent (produces VTK). But it does not disclose whether input .bi4 files are preserved, how filters interact, or 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 purpose sentence is front-loaded and the parameter list gives each argument a single efficient line. Compact enough that every line earns its place, though a dense arg-list format is slightly less scannable than prose 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, return values need no further explanation. The description covers purpose and all parameters. Minor gap: it doesn't clarify that job_id and dirdata are mutually exclusive alternatives with neither strictly required, nor whether at least one must be supplied for successful 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 fully compensates by documenting all 8 parameters with meaningful detail: relationships (dirdata as alternative to job_id), defaults (savevtk, onlytype), example values (variables '+idp,+vel,+rhop,+press'), and semantics (first/last as index range, onlytype as filter). Every parameter gains meaning 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?

States a specific verb (convert), a concrete input resource (Part_*.bi4 particle files), and an output format (VTK for visualisation). The purpose is unambiguous and clearly distinguishes it from siblings like gencase, run_case, and job_status, none of which perform file conversion.

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 'for visualisation' clause gives context for when the tool applies, and the sibling set makes the conversion role obvious. However, there is no explicit when-to-use guidance, no exclusions, and no mention of dependencies such as requiring a completed run_case/job_status before conversion is possible.

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