Review & rollback

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

Far exceeds the annotations: it discloses the automatic baseline creation, storage in a private git history under .godot/forge, that the user's own git is untouched, the git dependency, the Forge dock UI with Approve/Discard, that restore keeps the changeset open, that begin closes the previous changeset as accepted, that revert_changeset opens a new changeset, and that discard is destructive and needs user confirmation.

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 structure is exemplary for a 10-action tool: a short conceptual paragraph followed by one scannable line per action with inline parameter signatures. The introductory prose ('like a sandbox', the dock-button detail) is slightly chatty, but overall it is front-loaded and each action line earns its place.

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 no output schema, the description compensates by describing return shape per action (status returns the open changeset plus changed files; diff returns a unified diff plus stat; history returns past changesets with outcomes and ids). Combined with the mutation/destructive guidance and the git-dependency note, an agent has everything needed to invoke it correctly.

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 already 100%, so baseline is 3, but the description adds per-action parameter mapping and defaults that the schema does not convey (e.g. accept_previous?=true for begin, checkpoint as 'name or commit prefix', which actions take path/paths/id). This meaningfully exceeds the flat per-property schema descriptions.

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 opens by defining exactly what a changeset is (a reviewable/reversible baseline recorded automatically before the first edit) and then enumerates all 10 supported actions with their parameters. Despite the generic tool name 'changes', an agent immediately understands this is the changeset/rollback manager, and no sibling tool (files, project, exec, etc.) overlaps that scope.

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 explicit situational guidance per action: checkpoints before risky steps, restore if an approach fails, approve 'only when the user asked you to, or at the end of a task they approved', and discard only after confirming with the user. It also implicitly distinguishes restore (whole changeset) from revert_files (selected files) from revert_changeset (undo an approved changeset). It does not name alternative sibling tools, which keeps it just 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.