forge_save

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

The description reveals several behavioral traits: saving to disk, auto-commit to git, fallback to draft, and the conditional response based on verify_examples. Annotations already indicate destructive=true and readOnly=false, but the description adds specific context like auto-commit and doctor/regenerated_inspect responses. No contradiction.

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 a single paragraph that covers many aspects, but it is front-loaded with the main action. It could be broken into shorter sentences for readability, but it is not excessively long. Every sentence adds value.

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?

Despite no output schema, the description explains the response fields (doctor, regenerated_inspect) for the verify_examples case, and states the default doctor value. However, it does not describe the basic response structure when verify_examples is omitted, leaving a small gap.

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 60%, and the description adds meaning for plan, code, and verify_examples beyond the schema. However, site and name are not explained in the description, though they are implied. Overall, the description compensates well for the moderate schema coverage.

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 clearly states the tool's purpose: 'Save the tap to disk as .tap.json and auto-commit to git.' It distinguishes between preferred plan input and legacy code input, and mentions fallback to forge.draft session. This is specific and differentiates from sibling tools like forge_draft, forge_inspect, and tap_run.

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?

The description provides guidance on when to use plan vs code (plan preferred, code legacy), and mentions fallback to draft. It also explains the optional verify_examples hook and its consequences. However, it does not explicitly state when NOT to use this tool or list alternatives, so it is not a 5.

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