modelcontextprotocol / modelcontextprotocol/typescript-sdk

Semantics question: how should tool-call telemetry count cancelled or retried `tools/call` requests?

Open
#2,715 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
13.4k
Forks
2.2k
Avg merge
3d 15h
Merged PRs (30d)
4

Description

Background. The spec distinguishes protocol errors from tool execution errors reported via isError: true in CallToolResult, and the TypeScript SDK (v2 on main, 2026-07-28 spec) exposes client.callTool for tools/call.

Question or gap. For usage telemetry built on the SDK, what counts as "one tool call" when the client cancels mid-execution or times out and retries? Scenario: 1 agent tool intent → client times out at 30s and cancels (the server may still have completed the side effect) → client retries → 2 CallToolRequest/Result pairs for 1 logical invocation, where the first outcome is unknown, not failed. Counting request/response pairs yields 2 calls and 1 success; counting logical invocations yields 1 call. Which unit should SDK-level telemetry emit, and should "cancelled with unknown outcome" be a distinct outcome class from isError: true?

Proposed direction. Document a recommended outcome taxonomy for tool-call telemetry — executed-success / executed-isError / protocol-error / cancelled-outcome-unknown — so consumers building dashboards on the SDK count attempts consistently.

Non-goal. Not proposing a protocol change; just asking where counting semantics should be documented, since agents doing tool loops are the main users of these numbers.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the TypeScript SDK v2 client.callTool entry point and the tools/call CallToolRequest/CallToolResult behavior described in the issue. Review how cancellation, timeout, retry, protocol errors, and isError results are represented. Done means documenting a recommended telemetry taxonomy that distinguishes attempts, logical invocations, and cancelled outcomes with unknown results.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, observability
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.