bb_write_fileWrites text or base64-decoded bytes to a file via Blockbench's file layer, avoiding permission prompts. Use it to save generated models, scripts, or assets; parent directories must already exist.
Write text or base64-decoded bytes to a file, creating parent directories is the caller's job. Uses Blockbench's file layer (no permission prompt).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes | ||
| encoding | No | text |
Changes observed during successful MCP inspections.
v2.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the file-layer/no-permission behavior and the parent-directory constraint, but omits overwrite semantics (does an existing file get replaced?), error behavior, and return value — material gaps for a write operation.
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?
Two compact clauses, front-loaded with verb+resource and followed by caveats. The 'creating parent directories is the caller's job' phrasing is slightly clunky but every sentence carries information.
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?
For a 3-param write tool with no annotations and no output schema, the description covers the key operational constraints (no permission prompt, parent dirs) but leaves overwrite behavior and failure modes unspecified, which an agent would need to call it safely.
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 coverage is 0%, so the description must compensate. It explains the non-obvious encoding dimension ('text or base64-decoded bytes'), which maps to the enum, but adds nothing for path or content beyond what is self-evident. It partially rather than fully covers the 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 ('write') and resource ('file') plus the content types handled ('text or base64-decoded bytes'), which cleanly distinguishes it from siblings like bb_read_file and bb_delete_path. An agent can tell what this tool does without opening the schema.
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 note that 'creating parent directories is the caller's job' implicitly routes the agent to bb_mkdir first, and 'no permission prompt' hints at a contrast with bb_request_fs. However, no alternative is named explicitly and there is no clear when-to-use vs when-not statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.