next_path

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

Annotations declare readOnlyHint=false with destructiveHint=false, meaning calling this tool has some non-read side effect, yet the description never explains what state changes (presumably reserving/advancing a version). It does add useful behavioral context the schema lacks — that edit/thumbnail calls also return the user's rules 'once per chat,' implying per-session delivery semantics — but the source of the non-read-only flag remains undisclosed.

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 purpose, then compact per-kind pattern lines, then the call-before-write instruction. Information-dense with little waste, though the parenthetical asides ('plus an option word for several') are slightly compressed and require inference.

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?

There is no output schema, so the description must convey returns — and it does by specifying the returned path shape plus the per-chat rules payload. Combined with the fully documented input schema, an agent has almost everything needed; only the non-read-only side effect is left unstated.

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 100%, so the schema already documents kind, name, ext, group, library, and session. The description reinforces meaning by tying kind values to concrete output paths and by noting the -vN suffix is ignored and that library names can create new styles, but most of this duplicates schema text rather than extending it.

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 function — computing the target folder and next versioned filename for a new asset — and enumerates the exact path pattern for each of the three kinds (edit, thumbnail, library). An agent can immediately tell this is a path-allocation/query tool rather than a writer, though the naming of the tool itself carries less of the meaning than the format examples do.

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 gives an explicit sequencing instruction: 'Call it before you write any of these,' which tells the agent exactly when this tool is required relative to render/write operations. It does not state when it should NOT be used or name an alternative, but the conditional format rules function as routing guidance.

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