docs: SQL commenter and telemetry attributes by AjmeraParth132 · Pull Request #3281 · googleapis/mcp-toolbox

AjmeraParth132 · 2026-05-22T22:21:18Z

Description

Documentation Update for added SQLCommenter support, and telemetry_attributes exposure for client SDKs

PR Checklist

Make sure you reviewed
CONTRIBUTING.md
Make sure to open an issue as a
bug/issue
before writing your code! That way we can discuss the change, evaluate
designs, and agree on the general idea
Ensure the tests and linter pass
Code coverage does not decrease (if any source code was changed)
Appropriate docs were updated (if necessary)
Make sure to add ! if this involve a breaking change

🛠️ Fixes #3061

gemini-code-assist

Code Review

This pull request introduces documentation for per-call telemetry attributes in the Python SDK and a new SQL Commenter feature that propagates application context into database query logs. Feedback focused on improving technical accuracy and consistency, specifically by using 'prepending' instead of 'appending' to describe SQL comment placement and ensuring tool names follow the required snake_case convention. Additionally, suggestions were made to refine attribute descriptions with the correct metadata prefixes and project-specific terminology.

gemini-code-assist · 2026-05-22T22:24:01Z

 * **[Telemetry](telemetry/index.md)**: Learn how to configure logging levels and understand the core metrics and traces emitted by the Toolbox server.
-* **[Export Telemetry](export_telemetry.md)**: Discover how to deploy and configure an OpenTelemetry (OTel) Collector.
+* **[Export Telemetry](export_telemetry.md)**: Discover how to deploy and configure an OpenTelemetry (OTel) Collector.
+* **[SQL Commenter](sql_commenter.md)**: Propagate application context into database query logs by appending SQLCommenter-format comments to executed SQL statements.


For consistency with the implementation and the detailed documentation, 'prepending' should be used instead of 'appending'. Additionally, tool names must be in snake_case, so 'SQL Commenter' should be 'sql_commenter'.

Suggested change

* **[SQL Commenter](sql_commenter.md)**: Propagate application context into database query logs by appending SQLCommenter-format comments to executed SQL statements.

* **[sql_commenter](sql_commenter.md)**: Propagate application context into database query logs by prepending sql_commenter-format comments to executed SQL statements.

References

Tool names must be in snake_case.

gemini-code-assist · 2026-05-22T22:24:01Z

+type: docs
+weight: 10
+description: >
+  Propagate application context into database query logs by appending SQLCommenter-format comments to executed SQL statements.


The implementation and the example on line 57 show that the comment is prepended to the SQL statement, but the description uses the word 'appending'. For accuracy and consistency with line 51, 'prepending' should be used. Also, the tool name should be snake_case ('sql_commenter').

Suggested change

Propagate application context into database query logs by appending SQLCommenter-format comments to executed SQL statements.

Propagate application context into database query logs by prepending sql_commenter-format comments to executed SQL statements.

References

Tool names must be in snake_case.

gemini-code-assist · 2026-05-22T22:24:01Z

+convention that propagates application context into the database by appending a
+structured comment to every SQL statement before it is executed. The comment is


Similar to the description in the frontmatter, 'prepending' is more accurate here as the comment is added to the beginning of the statement.

Suggested change

convention that propagates application context into the database by appending a

structured comment to every SQL statement before it is executed. The comment is

convention that propagates application context into the database by prepending a

structured comment to every SQL statement before it is executed. The comment is

gemini-code-assist · 2026-05-22T22:24:01Z

+| `client`            | MCP client `_meta["dev.mcp-toolbox/telemetry"]["client.name"]` + `["client.version"]`.           | Identifies the SDK or application that initiated the MCP request.                              |
+| `client.model`      | MCP client `_meta["dev.mcp-toolbox/telemetry"]["client.model"]`.                                 | The LLM model that produced the tool call.                                                     |
+| `client.user.id`    | MCP client `_meta["dev.mcp-toolbox/telemetry"]["client.user.id"]`.                               | End-user identifier supplied by the client.                                                    |
+| `client.agent.id`   | MCP client `_meta["dev.mcp-toolbox/telemetry"]["client.agent.id"]`.                              | Agent identifier supplied by the client.                                                       |


The descriptions for the client-supplied attributes should include the params. prefix for the _meta field to be consistent with the explanation on line 75 and the MCP specification. Additionally, the description for the client attribute should clarify that the name and version are joined by a / separator, and use the project-specific term 'ADK' instead of 'SDK'.

Suggested change

| `client` | MCP client `_meta["dev.mcp-toolbox/telemetry"]["client.name"]` + `["client.version"]`. | Identifies the SDK or application that initiated the MCP request. |

| `client.model` | MCP client `_meta["dev.mcp-toolbox/telemetry"]["client.model"]`. | The LLM model that produced the tool call. |

| `client.user.id` | MCP client `_meta["dev.mcp-toolbox/telemetry"]["client.user.id"]`. | End-user identifier supplied by the client. |

| `client.agent.id` | MCP client `_meta["dev.mcp-toolbox/telemetry"]["client.agent.id"]`. | Agent identifier supplied by the client. |

| client | MCP client params._meta["dev.mcp-toolbox/telemetry"]["client.name"] and/or ["client.version"] (joined by /). | Identifies the ADK or application that initiated the MCP request. |

| client.model | MCP client params._meta["dev.mcp-toolbox/telemetry"]["client.model"]. | The LLM model that produced the tool call. |

| client.user.id | MCP client params._meta["dev.mcp-toolbox/telemetry"]["client.user.id"]. | End-user identifier supplied by the client. |

| client.agent.id | MCP client params._meta["dev.mcp-toolbox/telemetry"]["client.agent.id"]. | Agent identifier supplied by the client. |

References

Verify project-specific terminology and acronyms (such as 'ADK' for client orchestration frameworks) before assuming they are typos for more common terms (such as 'SDK').

gemini-code-assist · 2026-05-22T22:24:01Z

 | `--telemetry-gcp`          | bool     | Enable exporting directly to Google Cloud Monitoring. Default is `false`.                                                                                                                                 |
 | `--telemetry-otlp`         | string   | Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. "127.0.0.1:4318"). To pass an insecure endpoint here, set environment variable `OTEL_EXPORTER_OTLP_INSECURE=true`. |
 | `--telemetry-service-name` | string   | Sets the value of the `service.name` resource attribute. Default is `toolbox`.                                                                                                                            |
+| `--sql-commenter`          | bool     | Enable appending [SQLCommenter](../sql_commenter.md)-format comments to executed SQL statements. Default is `false`.                                                                                       |


For consistency with the implementation and the detailed documentation, 'prepending' should be used instead of 'appending'. Also, tool names must be in snake_case ('sql_commenter').

Suggested change

| `--sql-commenter` | bool | Enable appending [SQLCommenter](../sql_commenter.md)-format comments to executed SQL statements. Default is `false`. |

| --sql-commenter | bool | Enable prepending [sql_commenter](../sql_commenter.md)-format comments to executed SQL statements. Default is false. |

References

Tool names must be in snake_case.

anubhav756

@AjmeraParth132 Thanks for the PR!

Could you PTAL at the GCA comments?

I feel the prepend vs append make sense, because we seem to be actually prepending and not appending?

I also think this comment could be relevant as well? WDYT?

github-actions · 2026-05-29T08:23:54Z

🚀 Cloudflare Preview Ready!

🔎 View Preview: https://pr-3281.toolbox-docs-6xc.pages.dev

(Note: Subsequent pushes to this PR will automatically update the preview at this same URL)

anubhav756 · 2026-06-16T14:04:07Z

/gcbrun

anubhav756 · 2026-06-16T20:04:00Z

Closing this in favour of #3458

## Description Documentation update for added SQLCommenter support, and `telemetry_attributes` exposure for client SDKs > [!NOTE] > This PR supercedes the previous PR #3281 to update that with the latest changes from #3387. ## PR Checklist - [x] Make sure you reviewed [CONTRIBUTING.md](https://github.com/googleapis/mcp-toolbox/blob/main/CONTRIBUTING.md) - [x] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/mcp-toolbox/issues/new/choose) before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea - [x] Ensure the tests and linter pass - [x] Code coverage does not decrease (if any source code was changed) - [x] Appropriate docs were updated (if necessary) - [ ] Make sure to add `!` if this involve a breaking change 🛠️ Fixes #3061 --------- Co-authored-by: Parth Ajmera <[email protected]>

AjmeraParth132 requested a review from a team as a code owner May 22, 2026 22:21

blunderbuss-gcf Bot assigned Yuan325 May 22, 2026

gemini-code-assist Bot reviewed May 22, 2026

View reviewed changes

anubhav756 requested changes May 26, 2026

View reviewed changes

anubhav756 added the docs: deploy-preview Label to trigger Github Action docs preview. label May 29, 2026

anubhav756 force-pushed the feat/docs-update branch from a137cb3 to fcd05e2 Compare May 29, 2026 08:17

anubhav756 force-pushed the feat/docs-update branch from fcd05e2 to 5a489e3 Compare May 29, 2026 11:00

docs: SQL commenter and telemetry attributes

d28d338

anubhav756 force-pushed the feat/docs-update branch from 5a489e3 to d28d338 Compare June 16, 2026 14:03

docs: Replace global CLI flag with the tools.yaml configuration snippet.

0df540a

anubhav756 mentioned this pull request Jun 16, 2026

docs: SQL commenter and telemetry attributes #3458

Merged

6 tasks

anubhav756 closed this Jun 16, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: SQL commenter and telemetry attributes#3281

docs: SQL commenter and telemetry attributes#3281
AjmeraParth132 wants to merge 2 commits into
googleapis:mainfrom
AjmeraParth132:feat/docs-update

AjmeraParth132 commented May 22, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot May 22, 2026

Uh oh!

gemini-code-assist Bot May 22, 2026

Uh oh!

gemini-code-assist Bot May 22, 2026

Uh oh!

gemini-code-assist Bot May 22, 2026

Uh oh!

gemini-code-assist Bot May 22, 2026

Uh oh!

anubhav756 left a comment •

edited

Loading

Uh oh!

github-actions Bot commented May 29, 2026

Uh oh!

anubhav756 commented Jun 16, 2026

Uh oh!

anubhav756 commented Jun 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	* [SQL Commenter](sql_commenter.md): Propagate application context into database query logs by appending SQLCommenter-format comments to executed SQL statements.
	* [sql_commenter](sql_commenter.md): Propagate application context into database query logs by prepending sql_commenter-format comments to executed SQL statements.

	Propagate application context into database query logs by appending SQLCommenter-format comments to executed SQL statements.
	Propagate application context into database query logs by prepending sql_commenter-format comments to executed SQL statements.

		convention that propagates application context into the database by appending a
		structured comment to every SQL statement before it is executed. The comment is

	\| `--sql-commenter` \| bool \| Enable appending [SQLCommenter](../sql_commenter.md)-format comments to executed SQL statements. Default is `false`. \|
	\| --sql-commenter \| bool \| Enable prepending [sql_commenter](../sql_commenter.md)-format comments to executed SQL statements. Default is false. \|

Uh oh!

Conversation

AjmeraParth132 commented May 22, 2026

Description

PR Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

anubhav756 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 29, 2026

Uh oh!

anubhav756 commented Jun 16, 2026

Uh oh!

anubhav756 commented Jun 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

anubhav756 left a comment •

edited

Loading