The agent reads a directory and reports it empty — but it is full of files, and no error appears. Why?
The classic silent failure: relative path confusion. The server resolves paths against ITS working directory, not the client's and not the allowlist root you are mentally picturing. If the agent constructs ./src it may be querying the npx cache directory, receiving a legitimately empty listing, and confidently reporting your project has no source files. The engineering fix: instruct the agent to always use absolute paths anchored to the allowlisted root, and when a listing looks wrong, call directory_tree on the root first to re-anchor. Empty results in this server almost always mean wrong path, never missing data.
Can it follow symlinks outside the allowed directory?
Historically this was the escape hatch — a symlink inside the allowlist pointing to /etc could leak reads past the boundary. Current versions resolve and validate paths, but treat any repo with symlinks to sensitive locations as a boundary audit, not a footnote.
read_file vs read_multiple_files — does it matter?
Enormously. read_multiple_files batches reads in one call and reports per-file failures without aborting the batch. Ten sequential read_file calls cost ten tool round-trips of agent latency; one batch call costs one. For repo-scale context building, batching is the difference between a usable and an unusable workflow.
Is edit_file safe against clobbering concurrent changes?
No — it applies diff-style patches against the last-read state with no locking or mtime checks. If you edit the file in your IDE between the agent's read and write, the patch applies against stale content or fails with a mismatch. Treat agent edit sessions as exclusive write windows.