Skip to main content
Glama

export_asset

Destructive

Copy one revision to a file or up to 64 revisions to an existing directory outside the workspace, with custom filename templates and overwrite protection.

Instructions

Copy revisions' bytes out of the workspace. Pass either revision_id + dest_path (one file) or revision_ids + dest_dir (a batch of up to 64 into one existing directory; one failure does not abort the rest) - exactly one of the two forms. For a batch, filename_template (default "{revision_id}.{ext}") builds each file name from {revision_id} / {index} (1-based, zero-padded) / {ext} (from the MIME type) / {stem} (the file name the lineage was imported from); it must be a plain file name, and if two entries would collide nothing is written. Refuses to overwrite an existing file unless overwrite=true (ask the user first), and never writes inside the workspace store or through a symbolic link.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dest_dirNo書き出し先ディレクトリ(ワークスペース外、既存のディレクトリ)。 `revision_ids`(複数)専用。
dest_pathNo書き出し先パス(ワークスペース外)。`revision_id`(単数)専用。
overwriteNo既存ファイルを上書きしてよいか。既定 false(既存なら失敗する)。
revision_idNo書き出す revision ID("rev_...")。`revision_ids` とは排他で、どちらか一方が必須。
revision_idsNo複数 revision を1回で書き出す(1..=64 件)。`revision_id` とは排他。 このときは `dest_path` ではなく `dest_dir` を渡す。 1件が失敗してもバッチは中断せず、`failed` に理由が入る。
filename_templateNo`dest_dir` 内のファイル名の組み立て方。既定 `"{revision_id}.{ext}"`。 `revision_ids`(複数)専用。

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changedv0.6.4
    • addedInput schema / properties / dest_dir
      Added value: +{
      +  "description": "書き出し先ディレクトリ(ワークスペース外、既存のディレクトリ)。\n`revision_ids`(複数)専用。",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • changedInput schema / properties / dest_path / description
      Previous value: -"書き出し先パス(ワークスペース外)。"New value: +"書き出し先パス(ワークスペース外)。`revision_id`(単数)専用。"
    • changedInput schema / properties / dest_path / type
      Previous value: -"string"New value: +[
      +  "string",
      +  "null"
      +]
    • addedInput schema / properties / filename_template
      Added value: +{
      +  "description": "`dest_dir` 内のファイル名の組み立て方。既定 `\"{revision_id}.{ext}\"`。\n`revision_ids`(複数)専用。",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • changedInput schema / properties / revision_id / description
      Previous value: -"書き出す revision ID(\"rev_...\")。"New value: +"書き出す revision ID(\"rev_...\")。`revision_ids` とは排他で、どちらか一方が必須。"
    • changedInput schema / properties / revision_id / type
      Previous value: -"string"New value: +[
      +  "string",
      +  "null"
      +]
    • addedInput schema / properties / revision_ids
      Added value: +{
      +  "description": "複数 revision を1回で書き出す(1..=64 件)。`revision_id` とは排他。\nこのときは `dest_path` ではなく `dest_dir` を渡す。\n1件が失敗してもバッチは中断せず、`failed` に理由が入る。",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "array",
      +    "null"
      +  ]
      +}
    • removedInput schema / required
      Removed value: -[
      -  "revision_id",
      -  "dest_path"
      -]
    • addedOutput schema / $defs
      Added value: +{
      +  "BatchError": {
      +    "description": "バッチ要素の失敗理由。単一呼び出しが返す構造化エラーと同じ code / message。",
      +    "properties": {
      +      "code": {
      +        "type": "string"
      +      },
      +      "message": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "code",
      +      "message"
      +    ],
      +    "type": "object"
      +  },
      +  "BatchFailure": {
      +    "description": "バッチの1件分の失敗(パスと構造化エラーの要点)。",
      +    "properties": {
      +      "error": {
      +        "$ref": "#/$defs/BatchError"
      +      },
      +      "path": {
      +        "description": "入力で与えられたパス(または revision ID)。",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "path",
      +      "error"
      +    ],
      +    "type": "object"
      +  },
      +  "ExportAssetOutput": {
      +    "description": "`export_asset` の structuredContent。",
      +    "properties": {
      +      "byte_size": {
      +        "format": "uint64",
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "overwritten": {
      +        "description": "既存ファイルを上書きした場合 true。",
      +        "type": "boolean"
      +      },
      +      "path": {
      +        "description": "実際に書き出した絶対パス。",
      +        "type": "string"
      +      },
      +      "revision_id": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "revision_id",
      +      "path",
      +      "byte_size",
      +      "overwritten"
      +    ],
      +    "type": "object"
      +  },
      +  "ExportBatchOutput": {
      +    "description": "`export_asset`(バッチ)の structuredContent。",
      +    "properties": {
      +      "count": {
      +        "description": "書き出しに成功した件数(= `exported` の長さ)。",
      +        "format": "uint",
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "dest_dir": {
      +        "description": "書き出し先ディレクトリの絶対パス。",
      +        "type": "string"
      +      },
      +      "exported": {
      +        "description": "入力順の成功結果。",
      +        "items": {
      +          "$ref": "#/$defs/ExportAssetOutput"
      +        },
      +        "type": "array"
      +      },
      +      "failed": {
      +        "description": "失敗した revision(1件の失敗でバッチは中断しない)。",
      +        "items": {
      +          "$ref": "#/$defs/BatchFailure"
      +        },
      +        "type": "array"
      +      },
      +      "filename_template": {
      +        "description": "実際に使ったファイル名テンプレート(既定を含む)。",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "count",
      +      "exported",
      +      "failed",
      +      "dest_dir",
      +      "filename_template"
      +    ],
      +    "type": "object"
      +  }
      +}
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "$ref": "#/$defs/ExportAssetOutput"
      +  },
      +  {
      +    "$ref": "#/$defs/ExportBatchOutput"
      +  }
      +]
    • removedOutput schema / properties
      Removed value: -{
      -  "byte_size": {
      -    "format": "uint64",
      -    "minimum": 0,
      -    "type": "integer"
      -  },
      -  "overwritten": {
      -    "description": "既存ファイルを上書きした場合 true。",
      -    "type": "boolean"
      -  },
      -  "path": {
      -    "description": "実際に書き出した絶対パス。",
      -    "type": "string"
      -  },
      -  "revision_id": {
      -    "type": "string"
      -  }
      -}
    • removedOutput schema / required
      Removed value: -[
      -  "revision_id",
      -  "path",
      -  "byte_size",
      -  "overwritten"
      -]
  2. First observedv0.5.2

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds behavioral detail beyond them: overwrite is refused by default, collision in a batch writes nothing at all, execution never targets the workspace store or a symlink, and partial batch failure is tolerated. These are non-obvious operational traits worth stating.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then constraints ordered by invocation path. Every clause carries a real constraint, though the dense parenthetical chains make it heavier to parse than a few shorter sentences would be. No filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and the annotations carry the safety profile. Given the 6 parameters and the two-form invocation model, the description covers the exclusivity rule, defaults, failure behavior and write restrictions - nothing an agent needs is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already carries the baseline. The description goes further by pairing each form's parameters (revision_id + dest_path vs revision_ids + dest_dir), spelling out template placeholders ({revision_id}, {index} 1-based zero-padded, {ext} from MIME, {stem}) and the default template - meaning genuinely beyond what the structured fields convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Copy revisions' bytes out of the workspace') and names the exact scope: workspace bytes to an external path. It is naturally distinguishable from the inverse sibling import_asset and from list/inspect tools without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly declares the two mutually exclusive invocation forms ('exactly one of the two forms'), gives the batch cap (up to 64), notes that one failure does not abort the batch, and instructs the agent to ask the user before overwriting. This is full when/when-not guidance rather than implied context.

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