diff --git a/crates/g3-core/src/code_search.rs b/crates/g3-core/src/code_search.rs
index 1e4d38f..e4f7153 100644
--- a/crates/g3-core/src/code_search.rs
+++ b/crates/g3-core/src/code_search.rs
@@ -169,7 +169,7 @@ pub async fn execute_code_search(request: CodeSearchRequest) -> Result<CodeSearc
     
     // Execute searches concurrently
     let mut tasks = Vec::new();
-    
+
     for search in request.searches {
         let sem = semaphore.clone();
         let task = tokio::spawn(async move {
@@ -268,7 +268,7 @@ async fn execute_single_search(search: SearchSpec, max_matches: usize) -> Search
     };
     
     debug!("Executing ast-grep command: {:?}", cmd_args);
-    
+
     // Execute with timeout
     let timeout_duration = Duration::from_secs(timeout_secs);
     
diff --git a/crates/g3-core/src/lib.rs b/crates/g3-core/src/lib.rs
index e8f7569..2e33655 100644
--- a/crates/g3-core/src/lib.rs
+++ b/crates/g3-core/src/lib.rs
@@ -1154,6 +1154,8 @@ The tool will execute immediately and you'll receive the result (success or erro
 
 # Available Tools
 
+Short description for providers without native calling specs:
+
 - **shell**: Execute shell commands
   - Format: {\"tool\": \"shell\", \"args\": {\"command\": \"your_command_here\"}
   - Example: {\"tool\": \"shell\", \"args\": {\"command\": \"ls ~/Downloads\"}
@@ -1182,6 +1184,16 @@ The tool will execute immediately and you'll receive the result (success or erro
   - Format: {\"tool\": \"todo_write\", \"args\": {\"content\": \"- [ ] Task 1\\n- [ ] Task 2\"}}
   - Example: {\"tool\": \"todo_write\", \"args\": {\"content\": \"- [ ] Implement feature\\n  - [ ] Write tests\\n  - [ ] Run tests\"}}
 
+- **code_search**: Batch syntax-aware searches via ast-grep. Supports up to 20 pattern or YAML-rule searches in parallel.
+  - Format: {\"tool\": \"code_search\", \"args\": {\"searches\": [{\"name\": \"search_label\", \"mode\": \"pattern|yaml\", ...}], \"max_concurrency\": 4, \"max_matches_per_search\": 500}}
+  - Example for pattern mode: {\"tool\": \"code_search\", \"args\": {\"searches\": [{\"name\": \"find_functions\", \"mode\": \"pattern\", \"pattern\": \"fn $NAME($$$ARGS) { $$$ }\", \"language\": \"rust\", \"paths\": [\"src/\"]}]}}
+  - Example for YAML mode: {\"tool\": \"code_search\", \"args\": {\"searches\": [{\"name\": \"find_async\", \"mode\": \"yaml\", \"rule_yaml\": \"id: async-fn\nlanguage: Rust\nrule:\n  pattern: async fn $NAME($$$) { $$$ }\"}]}}
+  - Example for multiple searches: {\"tool\": \"code_search\", \"args\": {\"searches\": [{\"name\": \"funcs\", \"mode\": \"pattern\", \"pattern\": \"fn $NAME\", \"language\": \"rust\"}, {\"name\": \"structs\", \"mode\": \"pattern\", \"pattern\": \"struct $NAME\", \"language\": \"rust\"}]}}
+  - Example for passing optional args like \"context\": {\"tool\": \"code_search\", \"args\": {\"searches\": [{\"name\": \"funcs\", \"mode\": \"pattern\", \"context\": 3, \"pattern\": \"fn $NAME\", \"language\": \"rust\"}]}
+  - Common optional args for searches:
+       - \"context\": 3 (show surrounding lines),
+       - \"json_style\": \"stream\" (for large results)
+
 # Instructions
 
 1. Analyze the request and break down into smaller tasks if appropriate
@@ -1189,6 +1201,8 @@ The tool will execute immediately and you'll receive the result (success or erro
 3. STOP when the original request was satisfied
 4. Call the final_output tool when done
 
+For reading files, prioritize use of code_search tool use with multiple search requests per call instead of read_file, if it makes sense.
+
 Exception to using ONE tool at a time:
 If all you’re doing is WRITING files, and you don’t need to do anything else between each step.
 You can issue MULTIPLE write_file tool calls in a request, however you may ONLY make a SINGLE write_file call for any file in that request.