create_dataset_version

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

No annotations are provided, so the description must bear the full burden of behavioral transparency. It discloses the core behavior (create or update) but lacks detail on side effects (e.g., whether update is upsert, what happens if version_id doesn't exist), authentication requirements, rate limits, or error conditions. This is a significant gap for a mutation tool.

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 highly concise and well-structured, with clear headers for Create and Update sections and bullet-pointed required parameters. Every sentence adds value, and the information is front-loaded with the dual-purpose statement. No unnecessary words or redundancy.

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?

The description adequately covers the two operational modes and parameter usage but lacks context on return values (despite an output schema existing), error handling, idempotency, and required permissions. Given the tool's complexity (7 parameters, no annotations), the description is useful but not fully complete.

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?

With schema description coverage at 0%, the description adds essential meaning by mapping parameters to their roles in create and update operations. It specifies valid values for version_type (raw, qa_cleaned, training) and qa_status (pending, in_progress, ready, blocked), and explains qa_metadata as freeform JSON. This compensates well for the bare schema, though project_id and dataset_id are not elaborated.

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 creates or updates a dataset version, with specific sub-operations for each case. It distinguishes between create (registering an S3 file) and update (changing qa_status), providing a specific verb and resource. This clarity differentiates it from sibling tools which are primarily read or list operations.

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 detailed usage guidelines for the two internal modes (create vs update) by listing required parameters for each. However, it does not guide when to use this tool versus sibling tools like get_dataset_version or list_dataset_versions, leaving the agent to infer the appropriate alternative based on operation type.

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