Improve write_file fallback handling

src/agent_tool_specs/files.py

@@ -38,14 +38,34 @@ def build_file_tools(handlers: Mapping[str, ToolHandler]) -> list[AgentTool]:
         ),
         AgentTool(
             name='write_file',
-            description='Write a complete file inside the workspace. Creates parent directories when needed.',
+            description=(
+                'Write or append a UTF-8 text file inside the workspace. Creates parent directories when needed. '
+                'For multi-line content, prefer content_lines to reduce JSON escaping errors.'
+            ),
             parameters={
                 'type': 'object',
                 'properties': {
-                    'path': {'type': 'string'},
-                    'content': {'type': 'string'},
+                    'path': {'type': 'string', 'description': 'Relative path. output/, scratchpad/, and input/ route to the current session.'},
+                    'content': {'type': 'string', 'description': 'Full text content for short or simple files.'},
+                    'content_lines': {
+                        'type': 'array',
+                        'items': {'type': 'string'},
+                        'description': 'Lines to join with "\\n"; recommended for scripts, markdown, CSV, and other multi-line text.',
+                    },
+                    'content_base64': {
+                        'type': 'string',
+                        'description': 'Base64-encoded UTF-8 content. Use only when content contains many quotes or complex escaping.',
+                    },
+                    'append': {
+                        'type': 'boolean',
+                        'description': 'Append to an existing file instead of replacing it. Defaults to false.',
+                    },
+                    'newline_at_end': {
+                        'type': 'boolean',
+                        'description': 'Ensure the written text ends with a newline. Defaults to false.',
+                    },
                 },
-                'required': ['path', 'content'],
+                'required': ['path'],
             },
             handler=resolve_handler(handlers, 'write_file', 'file'),
         ),
@@ -108,4 +128,3 @@ def build_file_tools(handlers: Mapping[str, ToolHandler]) -> list[AgentTool]:
             handler=resolve_handler(handlers, 'grep_search', 'file'),
         ),
     ]
-