No output schema documentation. Tools return complex objects (e.g., base64 data, mime types, file paths) but no formal schema is visible in the tool definitions. LLMs cannot predict response structure or downstream data flow.
Parameter descriptions lack constraint details. E.g., 'Paper size (e.g. 'A4', 'LETTER')' lists examples in description instead of using enums; 'format_string' has no explanation of valid placeholders beyond the default; 'kind' in file_insert_section_break lacks validation rules.
No error handling guidance in tool descriptions. Destructive operations (file_delete_document) and complex operations (file_insert_html_end, file_search_and_replace) do not describe failure modes or recovery steps. An LLM cannot determine what to do if a delete or replace fails.
Recommendations
Add formal output schemas to tool definitions. For file_render_page_base64, document that it returns {base64: string, mime: string, ext: string}. This lets LLMs chain calls and extract the right data.
Convert example-based parameter descriptions to enum constraints. Replace '(e.g. 'A4', 'LETTER')' with a proper enum: ["A4", "LETTER", "LEGAL", "TABLOID", ...]. Same for 'kind' in file_insert_section_break: use enum ["nextPage", "continuous", "even", "odd"].
Add range constraints for numeric parameters. Document: 'dpi: integer, 50 - 600 (default: 150)', 'width_points: number, 1 - 2000', 'page_index: integer, 0 to (document total pages - 1)'.
Document placeholder syntax for format_string in file_add_page_numbering: '{PAGE} = current page, {NUMPAGES} = total pages. Other placeholders: {DATE}, {TIME}?', or explicitly list what is supported.
Add error handling and recovery guidance to destructive operations. E.g., file_delete_document: 'Permanently removes the document. If deletion fails, the file may still exist, verify with file_list_available_documents. This operation cannot be undone.'
Implement and document a confirmation step for file_delete_document. Add a required 'confirm_delete' parameter (boolean) that must be true, or return a 'dry_run' mode first. Require explicit confirmation to prevent accidents.
For file_list_available_documents, add a 'limit' parameter with a default of 20 and document pagination behavior. 'Returns up to <limit> documents (default: 20). Use offset parameter to paginate through results.'
No confirmation step for irreversible operations. file_delete_document is marked DESTRUCTIVE but has no dry-run or confirmation mechanism visible. Agents can delete files without a second chance.
Tool descriptions are generic and lack dependency hints. E.g., 'Get document information including size, word count, paragraph count, and page count' does not explain WHEN to call this vs file_get_document_text or file_get_document_outline. No guidance on which tools should be called in sequence.
Parameter 'directory' in file_list_available_documents has a default value of '.' but no guidance on search depth, permission requirements, or expected return limits. Will the tool scan recursively? Return 100 items or 10000?
Parameter 'options' in file_export_base64_advanced is a free-form object with no schema or examples. LLMs cannot discover valid keys or values, they must guess (embed_resources, useEmbedResources, embedImages, etc.). Should be an explicit schema or enum.
No validation rules visible for parameters like 'width_points', 'height_points', 'dpi', or 'page_index'. What are the valid ranges? Can DPI be 1? Can page_index exceed total pages? Will the tool clamp values or error?
file_add_picturefile_render_page_base64
Replace free-form 'options' parameter in file_export_base64_advanced with explicit, documented parameters OR a well-formed schema. Document which keys are valid for each 'fmt' value.
Add dependency hints to reading tools. E.g., file_get_document_info: 'Call this first to check document size and page count before rendering. Use file_get_document_text if you need raw content, or file_get_document_outline for structure.'
Document idempotency and side effects for each tool. E.g., file_add_picture: 'Appends to end of document. Calling twice with same image adds it twice, use file_search_and_replace to deduplicate.'
Clarify the lifecycle of 'filename' parameter. Once a file is created with file_create_document, does it persist on disk? How does it relate to the document store? Can the LLM pass arbitrary filenames or must they be pre-registered?