improve tool descriptions

Author: brendan-kellam

packages/web/src/features/tools/findSymbolDefinitions.txt

@@ -1 +1,8 @@
-Finds definitions of a symbol in the codebase.
+Finds where a symbol (function, class, variable, method, type, etc.) is defined in a repository.
+
+Usage:
+- Use this to answer "where is X defined/implemented?" questions.
+- Results include file paths and line numbers for each definition site, grouped by file.
+- Symbol matching is exact — use the precise identifier name, not a description (e.g., "UserService" not "user service class").
+- Prefer this over `grep` for symbol lookups: it understands symbol boundaries and won't match partial strings or comments.
+- If the repository name is not known, use `list_repos` first to discover the correct name.

packages/web/src/features/tools/findSymbolReferences.txt

@@ -1 +1,8 @@
-Finds references to a symbol in the codebase.
+Finds all usages of a symbol (function, class, variable, method, type, etc.) across a repository.
+
+Usage:
+- Use this to answer "where is X used/called?" questions.
+- Results include file paths and line numbers for each reference, grouped by file.
+- Symbol matching is exact — use the precise identifier name, not a description (e.g., "getUserById" not "get user by id").
+- Prefer this over `grep` for symbol lookups: it understands symbol boundaries and won't match partial strings or comments.
+- If the repository name is not known, use `list_repos` first to discover the correct name.

packages/web/src/features/tools/listCommits.txt

@@ -1 +1,10 @@
-Lists commits in a repository with optional filtering by date range, author, and commit message.
+Lists commits in a repository with optional filtering by message, date range, author, branch, and path.
+
+Usage:
+- Use `query` to search commit messages (case-insensitive). Supports substrings and simple patterns.
+- Use `since`/`until` for date filtering. Both ISO 8601 dates (e.g., "2024-01-01") and relative formats (e.g., "30 days ago", "last week", "yesterday") are supported.
+- Use `author` to filter by author name or email (case-insensitive, partial match).
+- Use `path` to limit results to commits that touched a specific file or directory.
+- Use `ref` to list commits on a specific branch, tag, or from a specific commit SHA. Defaults to the default branch.
+- Use `page`/`perPage` to paginate through large result sets. Check `totalCount` in the response to know if more pages exist.
+- If the repository name is not known, use `list_repos` first to discover the correct name.