Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server defines 4 tools with complete input schemas and parameter descriptions, placing it in the 'Fair' to 'Good' range. Tool naming follows verb conventions (get_, search_), and all parameters have types and descriptions. However, output schemas are not documented, and there is no explicit guidance on error recovery or what the LLM should do when a tool fails. The tools are focused on a single domain (OCI log querying) with appropriate read-only risk classification. Parameter descriptions are substantive (average ~80 chars), meeting baseline expectations. The main gaps are: (1) lack of documented return/output schemas, (2) no error-handling patterns to guide recovery, (3) parameter dependency documentation missing (e.g., country/countries are alternative ways to filter but this is not stated), and (4) tool composition could be improved, search_logs_by_country and search_logs_by_countries are near-duplicates.
Output schemas not documented. No explicit documentation of what fields each tool returns, forcing the LLM to infer response structure and increasing hallucination risk.
No error-handling guidance. Tools return {'error': str(exc)} on failure, but no description tells the LLM what to do: retry, ask user, or fail fast? This violates the recovery-guide pattern.
Parameter dependency undocumented: search_logs_by_country and search_logs_by_countries both filter by country/countries, but descriptions do not state whether they are mutually exclusive or if one is preferred. Similarly, search_logs_by_ip has both 'ip_address' and 'ip_range' params with defaults of null, and the description notes 'Only prefix-based matching is applied client-side', a non-obvious implementation detail that confuses tool usage.
Recommendations
Add explicit output schema documentation for each tool. Example: 'Returns a dict with keys: group_by (str), time_range (str), total (int), summary (list of dicts with keys: [field_name] (str), count (int)).' This lets the LLM know what to extract and chain to downstream tools.
Document error responses and recovery paths. Replace generic 'error' handling with specific guidance: 'If OCI_LOG_ID is invalid, error will be 'Log not found'. Verify credentials and OCI_LOG_ID environment variable are set correctly.' This guides the LLM's next action.
Consolidate search_logs_by_country and search_logs_by_countries into a single search_logs_by_country tool that accepts country: Union[str, list[str]]. Update the description to clarify: 'country can be a single country name or ISO code (str) or a list of them (list[str]). Both forms filter OCI logs to matching records.'
Document parameter dependencies explicitly. For search_logs_by_ip, update the description: 'Exactly one of ip_address or ip_range must be provided. ip_address filters for exact matches; ip_range applies prefix-based CIDR matching. If both are provided, ip_address takes precedence.' Add validation to reject ambiguous calls.
Add format/pattern constraints to time_range parameter. Clarify: 'time_range must match pattern \d+[hdw] (digits followed by h=hours, d=days, or w=weeks). Max lookback is 90 days. Example: 24h, 7d, 2w. Invalid formats will raise ValueError.'
Add limit constraints. Currently, get_traffic_analytics caps limit at 1000, but search_logs_by_country/country/ip default limit to 100 without a stated max. Unify: 'limit must be between 1 and 1000. Defaults to [value]. Higher limits may slow queries.' This prevents the LLM from requesting absurdly large result sets.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Tool composition: search_logs_by_country and search_logs_by_countries are near-duplicates (single country vs. array of countries). This wastes the LLM's reasoning cycles deciding between them. A single search_logs_by_country accepting both a scalar and array would be clearer.
Unclear time_range format. Descriptions say 'e.g. 24h, 7d, 2w' but do not state: (1) required format (regex pattern), (2) max lookback window, (3) behavior if format is invalid. The implementation raises ValueError on invalid unit, but the tool description does not document this or guide recovery.
Document which fields are returned by each search tool. E.g., 'search_logs_by_country returns a list of log entries. Each entry is a dict with keys matching OCI log schema (likely: timestamp, IP, Country, status, request, etc.). Consult OCI Logging docs for full field reference or use get_traffic_analytics to preview available fields.'
Add idempotence note. All four tools are read-only and should be idempotent. Explicitly state in tool descriptions: 'This tool only reads logs. Repeated calls with identical parameters return identical results and have no side effects.' This reassures the LLM that retries are safe.
Consider a discovery tool to help users explore schema. Add a describe_log_schema() tool that returns available fields in OCI logs (Country, IP, status, request, etc.). This enables the LLM to suggest valid group_by and filter values without guessing.
Add examples of valid input values where helpful. In group_by description, explicitly enumerate: 'Must be one of: country, ip, status_code, path.' This prevents LLM hallucination of other dimensions. Similarly, for country in search_logs_by_country: 'Country can be full name (e.g. United States) or ISO 2-letter code (e.g. US). Both forms are accepted and resolved to the same filter.'