Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
Single tool with basic but complete definition. Tool name 'search_in_file' follows verb_noun convention and clearly indicates the action. Input schema is present with proper JSON Schema structure including type, properties, and required fields. Descriptions exist but lack depth and specificity required for optimal LLM behavior. Parameter descriptions are minimal (10-30 chars) and do not include format constraints, ranges, or usage context. No output schema is documented, critical omission that prevents LLM from planning downstream operations. Error handling is present (GlobalExceptionHandler) but lacks actionable recovery guidance. The tool is read-only (good), but the overall definition lacks the richness needed for reliable agentic use.
Tools (1)
search_in_fileread onlysource verified67/100
Search for a keyword in a text file and return line matches with positions.
Missing output schema documentation. LLMs cannot plan downstream tool calls or extract data from results without knowing the structure of the response (e.g., does it return matched lines, line numbers, positions within lines, file context?).
Parameter descriptions are too brief (<30 chars each) and lack actionable constraints. 'Absolute or relative path to the file' doesn't specify: what happens with nonexistent files, what file types are supported, whether paths are validated server-side, or expected path format (Unix vs Windows). 'Keyword to search for' doesn't explain: is regex supported, what about special characters, case-sensitivity behavior, maximum length.
Tool description (64 chars) is at lower boundary of acceptable range (10-1024 chars baseline; optimal 50-200 for LLM context). It states WHAT the tool does but omits WHEN to use it (vs. alternative search approaches), what it returns, and prerequisites. For example: 'Search for a keyword in a text file and return line matches with positions' doesn't clarify whether results are sorted, paginated, or include surrounding context.
Recommendations
Add explicit output schema documentation in ToolMetadata.java. Example: 'Returns an object with fields: matches (array of {line_number, line_content, positions}), total_matches (integer), file_path (string), keyword (string), case_sensitive (boolean)'. This enables LLM reasoning about result structure.
Expand tool description to 100-150 chars with WHEN/WHAT/RETURN clarity. Example: 'Search for a keyword in a text file and return all matching lines with their positions. Use this to find references, definitions, or patterns in code/config files. Returns matches sorted by line number, up to 100 results.'
Add detailed parameter descriptions in ToolMetadata properties: file_path should specify 'Absolute or relative path to UTF-8 text file; must exist and be readable by the server process. Supports Unix and Windows paths. Max length 512 chars.' keyword should specify 'Search string to find in file. Case sensitivity controlled by case_sensitive param. Max 256 chars. Special regex chars (.*+?[]{}) treated as literals, not regex patterns.'
Document case_sensitive parameter behavior: 'If true, match case exactly. If false (default), all matches are case-insensitive. Does not affect whitespace or Unicode normalization.'
Add constraints to input schema: define maxLength for file_path (e.g., 512) and keyword (e.g., 256) in the JSON Schema properties to enforce limits at parse time.
Enhance error handling in GlobalExceptionHandler to provide recovery guidance. Example: For IOException, return '{"error": "File not found at path: /path/to/file", "recovery": "Verify the file exists and the path is correct. If the file is in a different location, try a different path."}'. For invalid keyword, return specific constraint violation.
No error handling guidance for LLM recovery. GlobalExceptionHandler catches IOException (file not found) and IllegalArgumentException but returns only error messages without suggesting next steps. For example: if file not found, should the LLM try alternative paths, list available files, or ask the user? Current 'error' field in response provides no recovery path.
case_sensitive parameter has default value but no description explaining its behavior. Does 'false' mean case-insensitive matching? What about Unicode normalization? Partial matches vs. whole-word? LLMs cannot infer from the parameter name alone and will guess, leading to unexpected behavior.
No input validation rules documented. Parameters accept any string, no constraints on file path format, keyword length, or file type. Without documented constraints, LLMs may pass extremely long keywords, invalid path characters, or binary files that cause silent failures or crashes. Constraints should be in parameter descriptions (e.g., 'keyword: 1-256 characters, no regex special chars unless escaped').
search_in_file
Add readonly security hint to tool metadata. Include 'readOnlyHint: true' in searchTool map (if using MCP 2026-07-28 spec) or document that this tool is read-only and has no side effects, allowing safe replay and caching.
Document file type support explicitly: 'Supports UTF-8 encoded text files (.txt, .log, .csv, .json, .yaml, .xml, code files). Binary files (.pdf, .zip, images) will fail with a clear error.'
Add example usage pattern to tool description if schema supports it: 'Commonly used to find specific log entries, locate function definitions, or search configuration values. Returns line numbers for easy navigation.'
Consider accepting multiple keywords or regex patterns in a future version, but document current limitation: 'Currently searches for exact literal string matches only. Regex patterns not supported in this version.'
Return pagination guidance if results exceed ~50 matches: 'If there are many matches (>100), consider narrowing the keyword to reduce noise. File must be <10MB for performance.'
Make tool idempotent and cacheable by documenting: 'Calling with the same file_path and keyword always returns identical results. Results are cached for 1 minute to reduce filesystem load.'