#113 Guide models from read_document to os.fs.read for source files

[Anonymous]

Originally created by: yablokolabs

Summary

Models can repeatedly choose os.fs.read_document for source files such as .py, receive an unsupported-extension error, try an invalid format: "text" override, and only later discover os.fs.read. Clearer tool descriptions and recovery guidance would save steps.

This is finding §10 from Yabloko Labs' evaluation. It is partly model behavior, but current descriptors and error text leave room for deterministic guidance.

Current behavior

The frequent-tool summary describes os.fs.read_document as PDF, Office, ODF, etc. but does not explicitly say to use os.fs.read for source code:

• default-tool-descriptors-a.ts (github.com)
• default-tool-descriptors-a.ts (github.com)

read_document supports a limited plain-text extension set; .py falls into the generic unsupported-extension error, which only suggests overriding format:

• read-document.ts (github.com)

That hint encourages guesses such as format: "text", while the accepted override is format: "plain".

Proposed behavior

Make tool selection and recovery unambiguous:

• os.fs.read: source code and normal UTF-8 text, with offset/limit pagination.
• os.fs.read_document: PDF/Office/ODF/RTF and intentional document extraction.
• For a source-like unsupported extension, return: Use os.fs.read for source/text files; if intentional, retry read_document with format: "plain".

Acceptance criteria

• The stable tool summaries explicitly distinguish source/text reads from document extraction.
• Unsupported source-like extensions name os.fs.read as the preferred next tool.
• The error names the valid format: "plain" override rather than the ambiguous word “format” alone.
• Existing document formats remain unchanged.
• Tests cover .py, .ts, .rs, an unknown binary extension, and a successful explicit format: "plain" override.
• Prompt regression tests pin the source-file guidance.