Create Version

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the mutation/non-destructive profile is covered. The description adds a real behavioral constraint not in the annotations – it requires enterprise write permission ('企业写门'), a gate that will block execution. That is genuinely useful, but the phrase is cryptic and nothing is said about failure modes when the version name already exists.

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?

A single front-loaded sentence with no filler; the scope and prerequisite come first. It is terse to the point of being clipped, but nothing is wasted.

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?

An output schema exists, so return values need not be explained, and annotations cover safety. But for a mutation tool with five undocumented parameters, a missing-parameter failure surface, and a cryptic permission prerequisite, the description leaves too much unstated for reliable invocation.

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% and there are five parameters, including required workspace_path, parent_version, and version_name. The description names none of them, so an agent gets no help on what parent_version should reference or what access_permission (default PRIVATE) controls. It fails to compensate for the total schema coverage gap.

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 ('创建命名版本' – create a named version) and scopes it to enterprise geodatabases or branch-versioning services. It distinguishes itself from the many read/list siblings, though it does not explicitly contrast with close cousins such as arcgis_pro_register_as_versioned or arcgis_pro_change_version.

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 names the environment where this applies (企业地理数据库 or branch version service) and states a prerequisite ('需要企业写门'), which implies when it is usable. However, it never says when to prefer this over sibling version tools (list_versions, reconcile_versions, post_version) or what to do if the parent version is not found, so usage is only implied.

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