fgui_create_branch

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

With no annotations provided, the description carries the full behavioral burden and does so: it discloses that the native project API is used, that changes are written to disk immediately ('立即落盘'), and that the operation is irreversible ('不可撤销'). It also flags the unsaved-document prerequisite, which is exactly the kind of side effect an agent must know before calling a mutation.

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?

Two sentences: the first front-loads purpose plus the irreversible-write warning, the second covers the two behavioral flags. No filler, and the most decision-relevant fact (irreversibility) comes before the parameter guidance.

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, the description covers the safety profile, persistence behavior, and conditional prerequisites, and an output schema exists so return values need no explanation. The only shortfall is the undocumented `verify` parameter, which an agent would have to guess at.

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 0%, so the description must compensate; it explains switch_to and save_open_documents including their interaction with unsaved state. `name` is self-evident, but `verify` (defaulting to true) is left completely unexplained, which is the one remaining gap in an otherwise strong compensation.

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 verb and resource ('create branch') plus an extra effect ('establish a branch root for each package'), so the agent knows exactly what will be produced. It distinguishes itself from the read-only siblings like fgui_list_branches by implication, but never names fgui_switch_branch as the alternative for switching, so sibling differentiation is only partial.

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 a clear conditional rule: set switch_to=True to activate the new branch after creation, and set save_open_documents=True when unsaved documents exist. That is real when-to-use guidance tied to state. It stops short of exclusions, e.g. whether to use this versus fgui_switch_branch when the branch already exists.

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