modelcontextprotocol / modelcontextprotocol/typescript-sdk
Semantics question: how should tool-call telemetry count cancelled or retried `tools/call` requests?
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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