@@ -15,7 +15,7 @@
 """AWS S3 Storage Lens tools for the AWS Billing and Cost Management MCP server.
 
 This module provides functionality to create and query Athena tables for S3 Storage Lens data.
-See the resources/storage_lens_metrics_reference.md file for detailed metrics information and sample queries.
+The storage-lens tool description lists the export columns and sample queries.
 """
 
 import asyncio
@@ -797,7 +797,7 @@ async def query_storage_lens(
 
 IMPORTANT USAGE GUIDELINES:
 - Before using this tool, provide a 1-3 sentence explanation starting with "EXPLANATION:"
-- Use standard SQL syntax for Athena queries
+- Dialect: Athena engine version 3 (Trino SQL). In CSV exports every column is a string, so cast before math or numeric comparison, e.g. SUM(CAST(metric_value AS BIGINT))
 - Reference the Storage Lens metrics table with the {table} placeholder (or its qualified <database>.<table> name). A query that does neither is rejected with a validation_error. Every {table} is replaced; nothing else in the query is changed
 - database_name and table_name, if given, must start with a letter and contain only letters, digits and underscores (at most 255 characters); other values are rejected with a validation_error
 - Perform aggregations (GROUP BY) when analyzing data across multiple dimensions
@@ -923,7 +923,14 @@ async def storage_lens_run_query(
         # Validate user-supplied query is a read-only SELECT
         validation_error = validate_query_is_readonly_select(query)
         if validation_error:
-            return format_response('error', {}, validation_error)
+            return format_response(
+                'error',
+                {},
+                validation_error,
+                error_type='validation_error',
+                operation='storage_lens_run_query',
+                service='Storage Lens',
+            )
 
         # Get manifest location from args or environment variable
         manifest_loc = manifest_location or os.environ.get(ENV_STORAGE_LENS_MANIFEST_LOCATION, '')
@@ -932,6 +939,9 @@ async def storage_lens_run_query(
                 'error',
                 {},
                 f"Missing manifest location. Provide 'manifest_location' parameter or set {ENV_STORAGE_LENS_MANIFEST_LOCATION} environment variable.",
+                error_type='validation_error',
+                operation='storage_lens_run_query',
+                service='Storage Lens',
             )
 
         # Get output location from args or environment variable (optional)
 
@@ -1443,6 +1443,71 @@ async def test_multi_statement_rejected(self, mock_context):
             mock_instance.query_storage_lens.assert_not_awaited()
 
 
+# --- Local validation errors carry error_type, operation and service ---
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    'query',
+    [
+        'DROP TABLE x',
+        'INSERT INTO t VALUES (1)',
+        'SELECT 1; DROP TABLE t',
+        '',
+        'SELECT FROM WHERE (',
+    ],
+)
+async def test_rejected_query_is_validation_error(mock_context, monkeypatch, query):
+    """A query rejected by the read-only check is a validation_error the caller must modify."""
+    monkeypatch.setenv('STORAGE_LENS_MANIFEST_LOCATION', 's3://bucket/prefix/')
+    stl_mod = _reload_storage_lens_with_identity_decorator()
+    with patch.object(stl_mod, 'StorageLensQueryTool') as MockTool:
+        res = await stl_mod.storage_lens_run_query(mock_context, query=query)  # type: ignore
+        MockTool.assert_not_called()
+    assert res['status'] == 'error'
+    assert res['message'].startswith('Query validation failed')
+    assert res['error_type'] == 'validation_error'
+    assert res['operation'] == 'storage_lens_run_query'
+    assert res['service'] == 'Storage Lens'
+    assert add_retry_guidance(res)['retry_strategy'] == 'modify_request'
+
+
+@pytest.mark.asyncio
+async def test_missing_manifest_location_is_validation_error(mock_context, monkeypatch):
+    """No manifest_location argument and no environment variable is a validation_error."""
+    monkeypatch.delenv('STORAGE_LENS_MANIFEST_LOCATION', raising=False)
+    stl_mod = _reload_storage_lens_with_identity_decorator()
+    res = await stl_mod.storage_lens_run_query(mock_context, query='SELECT 1')  # type: ignore
+    assert res['status'] == 'error'
+    assert 'Missing manifest location' in res['message']
+    assert res['error_type'] == 'validation_error'
+    assert res['operation'] == 'storage_lens_run_query'
+    assert res['service'] == 'Storage Lens'
+    assert add_retry_guidance(res)['retry_strategy'] == 'modify_request'
+
+
+@pytest.mark.asyncio
+async def test_description_states_dialect_and_csv_string_columns():
+    """The served description names the Trino dialect and that CSV export columns are strings."""
+    from awslabs.billing_cost_management_mcp_server.tools import storage_lens_tools as stl_mod
+
+    importlib.reload(stl_mod)
+    tool = await stl_mod.storage_lens_server.get_tool('storage-lens')
+    assert tool is not None
+    description = tool.description or ''
+    assert 'Athena engine version 3 (Trino SQL)' in description
+    assert 'In CSV exports every column is a string' in description
+    assert 'SUM(CAST(metric_value AS BIGINT))' in description
+    assert 'standard SQL' not in description
+
+
+def test_module_docstring_has_no_missing_file_pointer():
+    """The module docstring does not point at a reference file the package does not ship."""
+    from awslabs.billing_cost_management_mcp_server.tools import storage_lens_tools as stl_mod
+
+    assert 'storage_lens_metrics_reference.md' not in (stl_mod.__doc__ or '')
+
+
 # --- Direct unit tests for validate_query_is_readonly_select ---