Tool descriptions give insufficient guidance, causing avoidable mistakes

[shellicar]

Current behaviour

When I use PreviewEdit, Exec, and the read tools, the guidance I receive
is minimal. I make avoidable mistakes and need extra round-trips to recover.

For PreviewEdit, I have no clear guidance on when to use lineEdits vs
textEdits, or that line numbers always reference the file before the call.

For Exec, I don't always know when stdin is the right approach, or that
args are separate strings requiring no shell quoting.

More broadly, I often make unnecessary round-trips: calling a read tool,
waiting for the result, then deciding what to read next, when I could batch
reads upfront.

Desired behaviour

The tools I use most frequently give me enough guidance to avoid common
mistakes. Key areas:

• PreviewEdit: lineEdits vs textEdits distinction; line numbers reference
  the pre-edit file; combined example showing both
• Exec: structured args, no shell quoting, pipeline support, when to use stdin
• Read batching: call multiple reads before deciding what to write

Guidance

Open question on delivery: the improved tool instructions could be added to
tool description fields directly, or injected as a <system-reminder> block
in the system prompt. Descriptions are co-located with the tool; a system
prompt block keeps descriptions lean and surfaces the instructions at turn
start. Needs a decision before implementation.