renumber

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

With no annotations, the description carries the burden and does it well: it discloses that the operation renames files/folders, preserves the slug padded to collection width, and rewrites references repo-wide, plus that dry_run returns a plan without writing. It omits permissions, reversibility, and failure modes, keeping it out of 5 territory.

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?

Purpose and scope are front-loaded, then effects, then the parameter-specific clarifications. Dense but zero filler; each sentence adds distinct information.

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 mutation tool with no annotations and no output schema, the description covers side effects, the default-value behavior, and the preview mode well. It stops short of describing what the dry_run plan contains or what state the repo is left in on failure.

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 50% (only `to` and `ref` are documented in-schema), so the description must compensate. It explains the default for `to` ('coined as create does'), the path form of `ref` for duplicate pairs, and the semantics of `dry_run`, adding real meaning beyond the schema. `collection` remains unexplained in both places.

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 and resource ('Give an initiative a new number') and the exact motivating scenario (fixing a collision after a merge), then enumerates the concrete effects: file rename, asset folder rename, link and '<collection>#<n>' rewrites. This clearly distinguishes it from siblings like rename_collection and repad.

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?

Names a clear trigger ('fixing a number collision after a merge'), gives the disambiguating case for using `ref` as a path when handling one file of a duplicate-number pair, and flags the non-destructive dry_run path. It does not explicitly name sibling alternatives like repad or rename_collection, so it stops short of a 5.

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