opentel-mcp 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## 0.3.0
+
+### Added
+
+- OTel metrics, via `@opentelemetry/api`'s Metrics API only (no bundled
+  SDK/exporter — same host-app-provides-the-SDK pattern tracing already
+  uses):
+  - `mcp.tool.calls` (counter) — every tool call; `gen_ai.tool.name`,
+    `mcp.method.name`
+  - `mcp.tool.errors` (counter) — thrown/rejected handler; `gen_ai.tool.name`,
+    `error.type`
+  - `mcp.tool.silent_failures` (counter) — JSON-RPC succeeded but
+    `CallToolResult.isError === true`; `gen_ai.tool.name`
+  - `mcp.tool.duration` (histogram, unit `ms`) — call latency;
+    `gen_ai.tool.name`, `mcp.tool.outcome` (`success` | `error` |
+    `silent_failure`)
+  - `mcp.tool.silent_failures` fires from the same `isError` check that
+    marks the span ERROR — extracted into one shared `isToolResultError()`
+    helper in `src/instrument.js` so the detection logic isn't duplicated
+    between traces and metrics.
+  - Metrics are a zero-overhead no-op until the host application registers
+    a `MeterProvider` (default `@opentelemetry/api` behavior — not
+    special-cased here).
+- `enableMetrics` option (default `true`) to opt out of metric emission
+  without affecting tracing.
+
+### Naming note (no attribute rename)
+
+The tool-name attribute on all four new metrics is `gen_ai.tool.name`, not
+`mcp.tool.name` — the same spec-aligned name spans have used since v0.2's
+semantic-conventions pass (ADR 004). Traces and metrics were already
+consistent going into this release, so nothing was renamed here; this is
+called out because a naive read of the MCP semantic conventions might
+suggest a `mcp.tool.name` attribute, but the spec's actual server-span/
+metric attribute for this is `gen_ai.tool.name` (MCP tool calls are
+GenAI `execute_tool` calls under the hood — see `docs/adr/004-semantic-conventions-alignment.md`
+and `.spec-reference/mcp-semconv.md`). `mcp.method.name`, `error.type`,
+and `mcp.tool.argument_count` are unchanged. `mcp.tool.outcome` is a new
+custom (non-spec) attribute, documented in `src/attributes.js` alongside
+the other custom attribute.
+
+### Docs
+
+- README: new "Metrics" section (instrument table, `enableMetrics`, and a
+  `PeriodicExportingMetricReader` + OTLP/HTTP wiring example targeting
+  SigNoz's default local endpoint).
+- Roadmap updated to reflect metrics shipping in this release.
+
+## 0.2.0
+
+See git history — TypeScript declarations (`.d.ts`), workspace stripping
+for publish, and README documentation improvements.
+
+## 0.1.0
+
+Initial release: OTel tracing for MCP tool calls, including detection of
+`CallToolResult.isError: true` "silent failures" as `error.type: tool_error`
+span status.

package/README.md

@@ -2,7 +2,8 @@
 
 > OpenTelemetry instrumentation for Model Context Protocol (MCP) servers.
 > One-line visibility into which tools your AI agent is calling, how
-> long they take, and which ones fail — via standard OTel traces.
+> long they take, and which ones fail — via standard OTel traces and
+> metrics.
 
 [![CI](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/opentel-mcp.svg)](https://www.npmjs.com/package/opentel-mcp)
@@ -32,6 +33,65 @@ invocation with rich attributes, using standard OpenTelemetry APIs so
 it plugs into your existing observability stack (Jaeger, Grafana Tempo,
 Honeycomb, Datadog, whatever).
 
+## What you get
+
+MCP tool calls are invisible by default. When an agent turn takes 2.5
+seconds, you have no idea which tool caused it. opentel-mcp turns every
+tool call into an OpenTelemetry span you can read.
+
+### Example trace
+
+One agent turn, captured in Jaeger (spans generated by opentel-mcp,
+exported over OTLP):
+
+```
+agent_turn ............................. 2470ms   OK
+├─ tools/call search_documents ........... 46ms   OK
+├─ tools/call fetch_weather ............. 601ms   OK
+└─ tools/call generate_advice .......... 1802ms   OK   ← the bottleneck
+```
+
+Without tracing you'd know only that the turn took ~2.5s. With it, the
+waterfall shows `generate_advice` is where the time goes —
+`search_documents` and `fetch_weather` are cheap by comparison. That's
+the difference between guessing and knowing.
+
+### Tool-level failures
+
+An MCP tool can fail two ways: it can throw, or it can return
+`isError: true` on an otherwise-successful response. The second is how a
+tool reports a failure to the agent without crashing the server — and
+most instrumentation records it as a success, because the call
+technically succeeded.
+
+opentel-mcp catches it:
+
+```
+tools/call fetch_weather ................. 605ms   ERROR
+error.type = tool_error
+```
+
+The span is marked ERROR with `error.type = tool_error`, the result is
+returned to the agent unchanged, and nothing is thrown. Your error rate
+reflects reality instead of reading as a flat 100% success.
+
+### Span attributes
+
+Every span follows the OpenTelemetry MCP semantic conventions, so it
+drops into existing dashboards (Jaeger, Grafana Tempo, Honeycomb, SigNoz)
+with no custom mapping:
+
+| Attribute | Example value |
+|---|---|
+| `mcp.method.name` | `tools/call` |
+| `gen_ai.tool.name` | `generate_advice` |
+| `gen_ai.operation.name` | `execute_tool` |
+| `jsonrpc.request.id` | `3` |
+| `mcp.tool.argument_count` | `2` |
+
+Span name follows the spec's `{method} {target}` form (e.g.
+`tools/call generate_advice`), and span kind is `SERVER`.
+
 ## Quickstart (5-line usage)
 
 Works with either the low-level `Server` API:
@@ -110,6 +170,95 @@ Span status description carries the error message on failure (thrown
 errors); no separate error-message attribute is emitted — the spec
 expresses success/failure through span status, not a status attribute.
 
+## Metrics
+
+Alongside spans, opentel-mcp emits four `mcp.tool.*` metrics via
+`@opentelemetry/api`'s Metrics API — same API-only pattern as tracing (see
+"Two modes" below): no SDK or exporter is bundled, and recording is a
+zero-overhead no-op until the host application registers a
+`MeterProvider`. Set `enableMetrics: false` to opt out even when one is
+registered; tracing is unaffected either way.
+
+| Instrument | Type | Unit | Attributes | Emitted when |
+|---|---|---|---|---|
+| `mcp.tool.calls` | Counter | — | `gen_ai.tool.name`, `mcp.method.name` | Every tool call |
+| `mcp.tool.errors` | Counter | — | `gen_ai.tool.name`, `error.type` | The handler threw or its promise rejected |
+| `mcp.tool.silent_failures` | Counter | — | `gen_ai.tool.name` | The JSON-RPC response succeeded but `CallToolResult.isError` was `true` |
+| `mcp.tool.duration` | Histogram | `ms` | `gen_ai.tool.name`, `mcp.tool.outcome` (`success` \| `error` \| `silent_failure`) | Every tool call, on completion |
+
+`mcp.tool.silent_failures` is incremented from the exact same `isError`
+check that marks the span ERROR (see `isToolResultError()` in
+`src/instrument.js`) — the detection logic isn't duplicated between traces
+and metrics. `gen_ai.tool.name`, `mcp.method.name`, and `error.type` are
+the same spec-aligned attribute names the spans already use (see "Span
+attributes emitted" above); `mcp.tool.outcome` is a custom (non-spec)
+attribute, documented in `src/attributes.js`, that lets a single duration
+histogram distinguish thrown/protocol errors from silent failures without
+joining against `error.type`, which silent failures don't set on this
+metric.
+
+### Wiring a MeterProvider and TracerProvider (example: SigNoz)
+
+opentel-mcp never creates a `MeterProvider` itself (except the stderr/dev
+`setupNodeSdk: true` tracing path, which doesn't touch metrics) — register
+one the same way you would for any OTel-instrumented Node app, before
+calling `instrumentMcpServer()`. The same is true of the `TracerProvider`
+in bring-your-own-SDK mode (`setupNodeSdk: false`, the default): without
+registering one, `trace.getTracer()` inside opentel-mcp resolves to the
+`@opentelemetry/api` no-op default and spans are silently dropped, even
+though `mcp.tool.*` metrics keep flowing:
+
+```js
+import { metrics, trace } from '@opentelemetry/api';
+import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { NodeTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { instrumentMcpServer } from 'opentel-mcp';
+
+const resource = resourceFromAttributes({ 'service.name': 'my-mcp-server' });
+
+const meterProvider = new MeterProvider({
+  resource,
+  readers: [
+    new PeriodicExportingMetricReader({
+      exporter: new OTLPMetricExporter({ url: 'http://localhost:4318/v1/metrics' }),
+    }),
+  ],
+});
+metrics.setGlobalMeterProvider(meterProvider);
+
+const tracerProvider = new NodeTracerProvider({
+  resource,
+  spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }))],
+});
+tracerProvider.register();
+
+const server = new Server({ name: 'my-server', version: '1.0.0' }, {
+  capabilities: { tools: {} },
+});
+
+instrumentMcpServer(server, {
+  // setupNodeSdk: false (default) — this example brings its own SDK for
+  // both signals: the MeterProvider above for metrics, and the
+  // NodeTracerProvider above — registered globally via
+  // tracerProvider.register(), which is what trace.getTracer() picks up —
+  // for traces.
+});
+```
+
+`http://localhost:4318` is SigNoz's default local OTLP/HTTP endpoint (both
+`/v1/metrics` and `/v1/traces`); point it at your collector/SigNoz
+ingestion endpoint in production. `@opentelemetry/sdk-metrics` and
+`@opentelemetry/exporter-metrics-otlp-http` are peer/host-app
+dependencies — opentel-mcp doesn't bundle them (see the peerDependencies
+note in `package.json`). `@opentelemetry/sdk-trace-node` and
+`@opentelemetry/exporter-trace-otlp-http`, by contrast, are already
+runtime dependencies of opentel-mcp itself (used by its `setupNodeSdk: true`
+dev path), so no extra install is needed to use them here.
+
 ## Two modes
 
 **One-line (dev):** `setupNodeSdk: true` sets up a NodeTracerProvider
@@ -144,10 +293,11 @@ See ADR 002 in docs/adr/ for why.
 
 ## Roadmap
 
-- v0.2: OTel metrics (`mcp.server.operation.duration`,
-  `mcp.server.session.duration`) alongside traces, plus opt-in
-  `gen_ai.tool.call.arguments` support with a redaction callback
-- v0.3: W3C trace context propagation via `params._meta` per
+- Shipped in v0.3: `mcp.tool.*` metrics (see "Metrics" above). Opt-in
+  `gen_ai.tool.call.arguments` support with a redaction callback, and the
+  spec's own `mcp.server.operation.duration` / `mcp.server.session.duration`
+  metrics, remain unimplemented — tracked here, not silently dropped.
+- Next: W3C trace context propagation via `params._meta` per
   [SEP-414](https://modelcontextprotocol.io/community/seps/414-request-meta),
   plus client-side instrumentation, so a single trace can span the client
   call and the server's tool execution

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -14,6 +14,7 @@
   "files": [
     "src",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -56,6 +57,7 @@
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-metrics": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "typescript": "^7.0.2",
     "vitest": "^2.1.8"

package/src/attributes.js

@@ -63,3 +63,25 @@ export const ATTR_MCP_TOOL_ARGUMENT_COUNT = 'mcp.tool.argument_count';
 
 export const ATTR_MCP_SERVER_NAME = 'mcp.server.name';
 export const ATTR_MCP_SERVER_VERSION = 'mcp.server.version';
+
+/**
+ * NOT part of the MCP semantic conventions. Our own addition, on the
+ * mcp.tool.duration histogram (see src/metrics.js): which of the three
+ * call outcomes a given duration measurement belongs to. The spec's
+ * mcp.server.operation.duration metric (not yet implemented here — see
+ * README roadmap) expresses failure only via error.type; this attribute
+ * additionally distinguishes "thrown/protocol error" from "silent failure"
+ * (isError: true) so both are visible on the same histogram without
+ * requiring a join against error.type, which silent failures don't set
+ * on the duration metric.
+ */
+export const ATTR_MCP_TOOL_OUTCOME = 'mcp.tool.outcome';
+
+/** Well-known mcp.tool.outcome value: the call succeeded. */
+export const MCP_TOOL_OUTCOME_SUCCESS = 'success';
+
+/** Well-known mcp.tool.outcome value: the handler threw or its promise rejected. */
+export const MCP_TOOL_OUTCOME_ERROR = 'error';
+
+/** Well-known mcp.tool.outcome value: isError: true (see ERROR_TYPE_TOOL_ERROR above). */
+export const MCP_TOOL_OUTCOME_SILENT_FAILURE = 'silent_failure';

package/src/config.js

@@ -16,6 +16,10 @@ import { diag } from '@opentelemetry/api';
  *   Only takes effect when `setupNodeSdk` is true.
  * @property {boolean} [enabled=true] - Set to false to disable instrumentation entirely; instrumentMcpServer()
  *   becomes a no-op.
+ * @property {boolean} [enableMetrics=true] - Set to false to disable the mcp.tool.* metrics (tracing is
+ *   unaffected). Metrics are already a zero-overhead no-op when no MeterProvider is registered — the default
+ *   @opentelemetry/api behavior — so this flag exists for opting out even when one *is* registered, not as a
+ *   substitute for that default.
  * @property {boolean} [setupNodeSdk=false] - When true, instrumentMcpServer() creates and registers its own
  *   NodeTracerProvider (always exporting to stderr — safe alongside stdio-transport MCP servers, see ADR 003;
  *   additionally to `exporterUrl` via OTLP/HTTP if set). When false (the default), spans are emitted via
@@ -66,6 +70,7 @@ export function resolveOptions(options) {
     serviceName: opts.serviceName,
     exporterUrl: opts.exporterUrl,
     enabled: opts.enabled ?? true,
+    enableMetrics: opts.enableMetrics ?? true,
     setupNodeSdk,
   };
 }

package/src/index.d.ts

@@ -32,6 +32,19 @@ export interface InstrumentOptions {
    */
   enabled?: boolean;
 
+  /**
+   * Set to `false` to disable the `mcp.tool.*` metrics. Tracing is
+   * unaffected.
+   *
+   * Metrics are already a zero-overhead no-op when no `MeterProvider` is
+   * registered (the default `@opentelemetry/api` behavior) — this flag is
+   * for opting out of metrics even when a `MeterProvider` **is**
+   * registered, not a substitute for that default.
+   *
+   * @default true
+   */
+  enableMetrics?: boolean;
+
   /**
    * When `true`, {@link instrumentMcpServer} creates and registers its own
    * `NodeTracerProvider` (always exporting to stderr; additionally to

package/src/instrument.js

@@ -11,6 +11,7 @@ import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 import { resourceFromAttributes } from '@opentelemetry/resources';
 import { resolveOptions } from './config.js';
 import { StderrSpanExporter } from './exporters/stderr.js';
+import { setupMeter } from './metrics.js';
 import {
   ATTR_MCP_METHOD_NAME,
   ATTR_GEN_AI_TOOL_NAME,
@@ -21,6 +22,9 @@ import {
   ERROR_TYPE_TOOL_ERROR,
   GEN_AI_OPERATION_NAME_EXECUTE_TOOL,
   MCP_METHOD_NAME_TOOLS_CALL,
+  MCP_TOOL_OUTCOME_SUCCESS,
+  MCP_TOOL_OUTCOME_ERROR,
+  MCP_TOOL_OUTCOME_SILENT_FAILURE,
 } from './attributes.js';
 
 const require = createRequire(import.meta.url);
@@ -130,6 +134,7 @@ export function instrumentMcpServer(input, options) {
   assertInstrumentFirst(server);
 
   const tracer = setupTracer(server, resolved);
+  const metricsRecorder = resolved.enableMetrics ? setupMeter(PACKAGE_VERSION) : null;
   if (outer && server.shutdown) {
     outer.shutdown = server.shutdown;
   }
@@ -137,7 +142,7 @@ export function instrumentMcpServer(input, options) {
   const originalSetRequestHandler = server.setRequestHandler.bind(server);
   server.setRequestHandler = (schema, handler) => {
     if (schema === CallToolRequestSchema) {
-      handler = wrapToolCallHandler(handler, tracer);
+      handler = wrapToolCallHandler(handler, tracer, metricsRecorder);
     }
     return originalSetRequestHandler(schema, handler);
   };
@@ -207,9 +212,27 @@ function setupTracer(server, resolved) {
 }
 
 /**
- * Wraps a tools/call handler in a span covering its execution. This sits as
- * the innermost layer relative to Server's own request/response validation
- * wrapping (see ADR 001), so the span times exactly the real handler logic.
+ * True when `result` is a JSON-RPC-successful CallToolResult carrying a
+ * tool-level failure (isError: true) — the "silent failure" this package
+ * exists to catch (see the README's "Tool-level failures" section). Single
+ * source of truth for that detection: wrapToolCallHandler below keys both
+ * the span's status/error.type and the mcp.tool.silent_failures counter /
+ * mcp.tool.duration outcome off this same check, rather than repeating
+ * `result?.isError === true` at each call site.
+ *
+ * @param {*} result
+ * @returns {boolean}
+ */
+function isToolResultError(result) {
+  return result?.isError === true;
+}
+
+/**
+ * Wraps a tools/call handler in a span covering its execution, plus the
+ * mcp.tool.* metrics (see src/metrics.js). This sits as the innermost layer
+ * relative to Server's own request/response validation wrapping (see ADR
+ * 001), so both the span and the duration measurement time exactly the
+ * real handler logic.
  *
  * Span shape follows the MCP semantic conventions' server span (ADR 004):
  * name `{mcp.method.name} {target}` (falling back to just the method name
@@ -217,14 +240,15 @@ function setupTracer(server, resolved) {
  * error.type is set — which happens either because the handler threw, or
  * because it resolved successfully but returned a CallToolResult with
  * isError: true (a JSON-RPC-level success carrying a tool-level failure;
- * the spec calls this error.type value "tool_error"). In the isError case
- * the result is returned unchanged and nothing is thrown — the JSON-RPC
- * call itself succeeded.
+ * the spec calls this error.type value "tool_error", see
+ * isToolResultError() above). In the isError case the result is returned
+ * unchanged and nothing is thrown — the JSON-RPC call itself succeeded.
  *
  * @param {Function} handler
  * @param {import('@opentelemetry/api').Tracer} tracer
+ * @param {ReturnType<import('./metrics.js').setupMeter> | null} metricsRecorder
  */
-function wrapToolCallHandler(handler, tracer) {
+function wrapToolCallHandler(handler, tracer, metricsRecorder) {
   return (request, extra) => {
     const toolName = request?.params?.name;
     const spanName = toolName ? `${TOOLS_CALL_METHOD} ${toolName}` : TOOLS_CALL_METHOD;
@@ -240,19 +264,28 @@ function wrapToolCallHandler(handler, tracer) {
         span.setAttribute(ATTR_JSONRPC_REQUEST_ID, String(extra.requestId));
       }
 
+      metricsRecorder?.recordCall(toolName);
+      const startTime = performance.now();
+
       try {
         const result = await handler(request, extra);
-        if (result?.isError === true) {
+        if (isToolResultError(result)) {
           span.setAttribute(ATTR_ERROR_TYPE, ERROR_TYPE_TOOL_ERROR);
           span.setStatus({ code: SpanStatusCode.ERROR });
+          metricsRecorder?.recordSilentFailure(toolName);
+          metricsRecorder?.recordDuration(toolName, performance.now() - startTime, MCP_TOOL_OUTCOME_SILENT_FAILURE);
         } else {
           span.setStatus({ code: SpanStatusCode.OK });
+          metricsRecorder?.recordDuration(toolName, performance.now() - startTime, MCP_TOOL_OUTCOME_SUCCESS);
         }
         return result;
       } catch (err) {
         span.recordException(err);
         span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
-        span.setAttribute(ATTR_ERROR_TYPE, err?.name ?? 'Error');
+        const errorType = err?.name ?? 'Error';
+        span.setAttribute(ATTR_ERROR_TYPE, errorType);
+        metricsRecorder?.recordError(toolName, errorType);
+        metricsRecorder?.recordDuration(toolName, performance.now() - startTime, MCP_TOOL_OUTCOME_ERROR);
         throw err;
       } finally {
         span.end();

package/src/metrics.js

@@ -0,0 +1,87 @@
+/**
+ * @module metrics
+ * OpenTelemetry Metrics instruments for opentel-mcp.
+ *
+ * Follows the same @opentelemetry/api-only pattern as tracing (see
+ * setupTracer() in instrument.js): instruments come from
+ * metrics.getMeter(), which resolves to whatever MeterProvider the host
+ * application has already registered globally, or the API's built-in
+ * no-op implementation if none has. This module never creates or
+ * registers a MeterProvider itself — recording through it is a
+ * zero-overhead no-op until the host does. See config.js's enableMetrics
+ * option for the opt-out, and the README's "Metrics" section for how to
+ * wire up a real MeterProvider.
+ *
+ * Unlike @opentelemetry/api's tracing API, its metrics API (as of
+ * @opentelemetry/api ^1.9) does not proxy a not-yet-registered
+ * MeterProvider — metrics.getMeter() resolves the current global
+ * synchronously at call time rather than lazily delegating later. So, as
+ * with setupTracer(), setupMeter() must run after the host application has
+ * registered its MeterProvider (the same ordering the README already
+ * documents for tracing).
+ */
+
+import { metrics } from '@opentelemetry/api';
+import {
+  ATTR_MCP_METHOD_NAME,
+  ATTR_GEN_AI_TOOL_NAME,
+  ATTR_ERROR_TYPE,
+  ATTR_MCP_TOOL_OUTCOME,
+  MCP_METHOD_NAME_TOOLS_CALL,
+} from './attributes.js';
+
+/**
+ * Creates the mcp.tool.* instruments and returns small record*() wrappers
+ * around them, keyed to the well-known attribute names above so call
+ * sites in instrument.js never construct attribute bags by hand.
+ *
+ * @param {string} packageVersion
+ * @returns {{
+ *   recordCall: (toolName: string | undefined) => void,
+ *   recordError: (toolName: string | undefined, errorType: string) => void,
+ *   recordSilentFailure: (toolName: string | undefined) => void,
+ *   recordDuration: (toolName: string | undefined, durationMs: number, outcome: string) => void,
+ * }}
+ */
+export function setupMeter(packageVersion) {
+  const meter = metrics.getMeter('opentel-mcp', packageVersion);
+
+  const calls = meter.createCounter('mcp.tool.calls', {
+    description: 'Number of MCP tool calls received, regardless of outcome.',
+  });
+  const errors = meter.createCounter('mcp.tool.errors', {
+    description: 'Number of MCP tool calls whose handler threw or rejected (protocol-level failure).',
+  });
+  const silentFailures = meter.createCounter('mcp.tool.silent_failures', {
+    description:
+      'Number of MCP tool calls whose JSON-RPC response succeeded but whose CallToolResult had isError: true.',
+  });
+  const duration = meter.createHistogram('mcp.tool.duration', {
+    description: 'Duration of MCP tool call execution.',
+    unit: 'ms',
+  });
+
+  return {
+    recordCall(toolName) {
+      calls.add(1, {
+        [ATTR_GEN_AI_TOOL_NAME]: toolName,
+        [ATTR_MCP_METHOD_NAME]: MCP_METHOD_NAME_TOOLS_CALL,
+      });
+    },
+    recordError(toolName, errorType) {
+      errors.add(1, {
+        [ATTR_GEN_AI_TOOL_NAME]: toolName,
+        [ATTR_ERROR_TYPE]: errorType,
+      });
+    },
+    recordSilentFailure(toolName) {
+      silentFailures.add(1, { [ATTR_GEN_AI_TOOL_NAME]: toolName });
+    },
+    recordDuration(toolName, durationMs, outcome) {
+      duration.record(durationMs, {
+        [ATTR_GEN_AI_TOOL_NAME]: toolName,
+        [ATTR_MCP_TOOL_OUTCOME]: outcome,
+      });
+    },
+  };
+}