Skip to main content
Glama
Sign In

AskYourStack

by com.askyourstack
OverviewDiscussionsAdmin

Write a file

write_file
Destructive

Create or replace a file. Keeps owner and mode of an existing file and saves its previous version under /var/lib/askyourstack/backups. Parent folders are created. Give the text as content, or a file from this conversation (an image generated here or one the user attached, up to 15 MB) as file, for example a picture into a shop's pub/media or wp-content/uploads folder; make it readable by the web server's user afterwards if the folder needs that.

Input Schema

NameRequiredDescriptionDefault
whyNoOne plain sentence for the user, shown on the approval page if this call needs their approval: what it does and why it is needed.
fileNoA file from this conversation, written as it is (its bytes, not text).
modeNoOctal, like 0644. Default: keep existing, or 0644.
pathYes
serverNoServer name or id. Optional when the account has one server.
contentNoThe file's text, or its bytes in base64 with encoding base64. Leave out when file is given.
encodingNo
approval_idNoOnly when repeating a call the user approved.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / content / description
      Added value: +"The file's text, or its bytes in base64 with encoding base64. Leave out when file is given."
    • addedInput schema / properties / file
      Added value: +{
+  "additionalProperties": false,
+  "description": "A file from this conversation, written as it is (its bytes, not text).",
+  "properties": {
+    "download_url": {
+      "type": "string"
+    },
+    "file_id": {
+      "type": "string"
+    },
+    "file_name": {
+      "type": "string"
+    },
+    "mime_type": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "download_url",
+    "file_id"
+  ],
+  "type": "object"
+}
    • changedInput schema / required
      Previous value: -[
-  "path",
-  "content"
-]New value: +[
+  "path"
+]
  2. First observed

TDQS

A4/5.0
Behavior4/5

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

Rich disclosure beyond the annotations: backup path for the previous version, owner/mode preservation, automatic parent folder creation, a 15 MB cap on conversation files, and a nudge to fix readability for the web server user. It doesn't describe failure behavior or what the call returns, but for a destructive write this is well above the bar set by destructiveHint=true.

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?

Effectively three sentences, front-loaded with the action and its main consequences, then the input choice, then the caveat. Slightly overloaded with semicolon-joined clauses in the last sentence, but no filler.

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

Completeness3/5

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

Covers the destructive-write semantics, backup and permission behavior, and the content/file split, which is most of what an agent needs. With 8 params, a nested object, an approval flow and no output schema, it still omits how the approval_id/why round trip works and what happens on failure.

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?

At 75% schema coverage and 8 params, the description still adds real meaning: content is text (or base64 via encoding), file is a binary from the conversation with a size limit not stated in the schema, and mode relates to who can read the result. Parameters like why, approval_id and server are left entirely to the schema.

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 — 'Create or replace a file' — in the very first sentence, and immediately clarifies that replacement preserves owner/mode and backs up the prior version. This clearly separates it from read_file and from content-writing siblings like content_save.

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

Usage Guidelines3/5

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

It explains the content-vs-file choice with a concrete example ('a picture into a shop's pub/media or wp-content/uploads folder'), which is useful guidance, but usage is only implied. No sibling alternative is named (read_file, content_upload, content_save) and there is no when-not guidance.

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

All AskYourStack toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources