Add SQLCommenter observability to all sources

[tanujbolisetty]

Prerequisites

• Search the current open issues

What are you trying to do that currently feels hard or impossible?

Summary

Introduce a centralized SQLCommenter integration that automatically appends
metadata (action, controller, db_driver, traceparent) to every
database request (SQL statements and BigQuery job labels). This will give
operators full trace correlation between AI‑driven tool calls and the
underlying database activity.

Motivation

• Unified observability – no longer need to sprinkle manual comment logic
  in each tool implementation.
• Trace correlation – the OpenTelemetry traceparent tag lets Cloud
  Monitoring link the AI request to the database query.
• Zero runtime overhead – only a string concatenation before the query is
  executed.
• Future‑proof – new database sources automatically inherit the behavior.

Suggested Solution(s)

Proposed Design (high‑level)

1. Core helper – internal/sqlcommenter/commenter.go will expose
   AppendComment(ctx, sql) that reads the request context for:
   • toolName (the tool being executed)
   • controller (the agent name, from TOOLBOX_AGENT_NAME)
   • db_driver (derived from the source type)
   • traceparent (from the current OpenTelemetry span, if any)
2. Context injection – modify internal/server/api.go (and the MCP
   method files) to store toolName and controller in the request context
   before the tool handler runs.
3. Source updates – each source’s RunSQL method calls
   sqlcommenter.AppendComment before executing the query.
   This includes Postgres, MySQL, BigQuery, SQLite, MSSQL, CockroachDB,
   AlloyDB, SingleStore, etc.
4. BigQuery job labels – the same tags are added to JobLabels so they
   appear in Cloud Logging.
5. OpenTelemetry – add the traceparent tag to enable end‑to‑end tracing.
6. Tests – add unit tests (internal/sqlcommenter/commenter_test.go) that
   verify the generated comment contains all fields when the context is set.
7. Documentation – add a design note in docs/sqlcommenter_design.md

Alternatives Considered

No response

Additional Details

No response