| 1 | # Tool Usage Notes |
| 2 | |
| 3 | Tool signatures are provided automatically via function calling. |
| 4 | This file documents non-obvious constraints and usage patterns. |
| 5 | |
| 6 | ## glob — File Discovery |
| 7 | |
| 8 | - Use `glob` to find files by pattern before falling back to shell commands |
| 9 | - Simple patterns like `*.py` match recursively by filename |
| 10 | - Use `entry_type="dirs"` when you need matching directories instead of files |
| 11 | - Use `head_limit` and `offset` to page through large result sets |
| 12 | - Prefer this over `exec` when you only need file paths |
| 13 | |
| 14 | ## grep — Content Search |
| 15 | |
| 16 | - Use `grep` to search file contents inside the workspace |
| 17 | - Default behavior returns only matching file paths (`output_mode="files_with_matches"`) |
| 18 | - Supports optional `glob` filtering plus `context_before` / `context_after` |
| 19 | - Supports `type="py"`, `type="ts"`, `type="md"` and similar shorthand filters |
| 20 | - Use `fixed_strings=true` for literal keywords containing regex characters |
| 21 | - Use `output_mode="files_with_matches"` to get only matching file paths |
| 22 | - Use `output_mode="count"` to size a search before reading full matches |
| 23 | - Use `head_limit` and `offset` to page across results |
| 24 | - Prefer this over `exec` for code and history searches |
| 25 | - Binary or oversized files may be skipped to keep results readable |