ncloud_ncs_list_object_versions

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

Annotations declare readOnlyHint=true, and the description aligns (it lists versions, doesn't mutate). The description adds context about pagination parameters (keyMarker/versionIdMarker) but does not describe what happens when a bucket is not versioning-enabled or whether delete markers are included even when they are empty. No contradiction with annotations.

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 two sentences long, front-loads the core action, and packs useful context (versions, delete markers, API reference, use cases) without fluff. It could arguably be trimmed, but every sentence 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?

Given the readOnly annotation, the parameter schema, and a simple list operation, the description provides enough context for an agent to call it correctly. It doesn't describe response structure, but there's no output schema, and for a list operation the response shape (versions/delete markers) is fairly inferable from the purpose. It also doesn't mention the exact behavior when versioning is disabled, which is a minor 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 100%, so all parameters are documented in the schema. The description reinforces the pagination parameters (keyMarker/versionIdMarker) indirectly and mentions the bucket context, but it doesn't add much beyond the schema. However, it clarifies that the operation targets a 'versioning-enabled' bucket, which is semantically relevant for bucketName.

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 with a specific verb and resource ('List all versions and delete markers of objects in a versioning-enabled Ncloud Storage bucket') and even names the underlying API (GET /?versions). It clearly distinguishes this from sibling tools like ncloud_ncs_list_objects or ncloud_list_object_versions by specifying versions/delete markers, making the tool's purpose unambiguous.

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 concrete use cases: 'Use it to find noncurrent versions to restore or delete, and to empty a versioned bucket before deleting it.' This tells an agent when to invoke it. It doesn't explicitly say when not to use it or name an alternative tool, but the provided use cases are specific enough to guide selection.

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