Standardize AI tool results as structured JSON

[haizhi03]

Chat2DB Edition

Chat2DB Community

User Problem

Problem

AI database tools currently return free-form text with inconsistent formats across tools.

For example, metadata tools may return newline-separated text, schema tools may return DDL-like text,
and SQL execution tools may return table-like text mixed with status fields. This makes it harder for
the model and other tool consumers to reliably determine:

• whether the tool call succeeded
• which tool produced the result
• what data should be consumed
• what error occurred
• how SQL result columns map to row values

This is especially fragile for execute_sql, where the model has to infer rows and columns from a
text/table preview.

Proposed solution

Introduce a standard JSON result contract for AI tool outputs:

{
  "success": true,
  "tool": "execute_sql",
  "summary": "...",
  "data": [],
  "errorCode": null
}

Each AI tool should return this shape consistently.

Expected behavior:

• success indicates whether the tool call succeeded.
• tool identifies the tool name.
• summary provides a human-readable summary.
• data contains structured payloads such as datasource lists, table lists, schema information, or
  SQL result rows.
• errorCode provides a stable failure reason when success is false.

Scope

Standardize result output for these AI database tools:

• list_all_datasources
• list_all_databases
• list_all_schemas
• list_all_tables
• get_tables_schema
• execute_sql

Also ensure adapter-level failures, including MCP tool failures, return the same JSON shape.

Benefits

• Improves model reliability when consuming tool results.
• Avoids parsing table-like or natural-language text for SQL results.
• Provides a consistent format for both success and failure.
• Makes AI trace rendering and future frontend display easier.
• Makes MCP tool result handling more predictable.

Related PR: #1876

Product area

AI

Proposed outcome

AI database tool results should use a consistent JSON structure so the model can reliably consume
success state, error information, schema metadata, and SQL result rows from fixed fields instead of
parsing free-form text.