Preview or apply a release version bump

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

With only destructiveHint=true in annotations, the description carries the behavioral burden and does so thoroughly: it states dry_run writes nothing, and an apply touches version targets, pins, changelog, lockfiles, generated assets, and git branch/commit. It also promises changed_paths on every result, so the agent knows what side effects to expect.

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 is front-loaded with the purpose, default, and parameter semantics, and every paragraph is information-dense. The final paragraph largely repeats the pipeline stages and adds a defect-history note that is not needed for invocation, so it is not perfectly concise.

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 destructive tool with an output schema, the description covers all parameters, defaults, scoping behavior, side effects, and result fields. Nothing an agent needs to select or invoke it correctly is missing.

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 0%, and the description fully compensates by enumerating valid level values, defining dry_run's default and effect, and explaining group as a [tool.rrt] version group that can be omitted to bump all groups. This is exactly the semantic information the bare schema lacks.

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 first sentence names a specific action and resource: preview or apply a version bump. It also establishes that this is the full rrt bump pipeline rather than a manual version-string edit, so an agent can tell it apart from inspection tools like rrt_version and from hand-editing.

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 explicitly says to use the tool instead of editing version strings by hand, gives the dry_run=True default for safe previews, and explains the group parameter for restricting vs bumping all configured groups. The equivalence to the rrt bump CLI also clarifies when the same repo-wide result is expected.

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