ptfx_pack

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description usefully adds that the tool writes a .ypt and reads .dds files from a sibling directory, plus what verify actually does (re-converts and compares rule by rule). It does not disclose overwrite behavior for an existing output file, failure modes for missing .dds assets, or what the call returns.

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 dense sentences with no filler; the core operation and its format constraints come first, followed by the verify side-effect. Nothing is redundant with the title or 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?

For a file-mutating tool with thin annotations, no output schema, and one undocumented parameter, the description covers the happy path well but leaves gaps around output location, overwrite semantics, and return value. An agent could invoke it but would be guessing on the out parameter.

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 only 33% (just 'xml: absolute path'), so the description must compensate. It does explain verify's meaning and its default of true, which the schema omits, but says nothing about the 'out' parameter, its default, or how the sibling <name>/ folder is derived from xml.

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?

Specific verb and resource: builds a Legacy (gen8, resource v68) .ypt from a .ypt.xml plus the .dds files in the sibling <name>/ folder. The inputs and output format are concrete enough to separate it from ptfx_unpack or ptfx_edit, though no sibling is named to make the distinction explicit.

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?

Usage is only implied by the verb 'build' and the stated input layout; there is no explicit when-to-use, when-not-to-use, or named alternative. An agent can infer this is the packing step of a round-trip workflow, but must guess at prerequisites such as whether the sibling folder must already exist.

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