Define consistent strict and diagnostic validation for client list APIs

Open
#1,997 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
csharp

Research direction

Start by reading related issues #1996, #1993, and #1645 to understand the aggregation boundary, prior Skills APIs, and page-level cache hints. Then inspect the client list APIs for tools, prompts, resources, resource templates, and Skills, along with their tests and source-generated serialization paths. Define the shared validation and diagnostic behavior while preserving strict defaults, pagination and fatal page errors; add the mixed-page, later-page, rejection-position, and failure tests listed in the issue.

Written by the indexing model from the issue text.

Description

P3

Summary

Evaluate a consistent validation contract for client list APIs for tools, prompts, resources, resource templates, and Skills, including an optional diagnostic path that exposes usable entries alongside explicit rejected-entry details.

Preserve existing strict defaults. This is separate from how many pages or entries a caller permits the SDK to fetch.

Motivation

A single malformed entry can prevent a host from using otherwise valid entries in a listing. Hosts may want to inspect individual failures, but silently dropping invalid entries would make an incomplete result look complete.

Skills previously had dedicated ListSkillsWithDiagnosticsAsync, SkillListingResult, and SkillEntryRejection APIs. #1993 removes that Skills-only design so equivalent concepts can be evaluated consistently across the SDK.

Proposed scope

  • Document the shared validation contract and any primitive-specific checks. Passing SDK structural checks must not be described as establishing trust or, for Skills, verifying file contents/frontmatter.
  • Evaluate an explicit opt-in diagnostic API or mode that returns accepted entries and rejection details, including original entry positions and actionable errors. Do not silently omit rejected entries.
  • Preserve page boundaries, continuation cursors, and page-level cache hints where appropriate. Do not invent a single aggregate TTL.
  • Distinguish recoverable individual-entry failures from malformed JSON, invalid envelopes, or missing/null required list members where a page cannot safely be recovered. Do not turn these into success-shaped empty results.
  • Preserve ordinary RPC failure and cancellation behavior, and support the SDK's source-generated/Native AOT serialization paths.
  • Test mixed valid/invalid pages, failures on later pages, rejection positions, fatal page errors, strict defaults, and the opted-in diagnostic behavior.

Boundaries

Do not bundle aggregation budgets, caching policy, or server-side pagination infrastructure into this issue. Existing single-page APIs remain the escape hatch for application-owned policy.

Coordinate with the aggregation-budget design on entry counting and incomplete-result reporting, while keeping the two policies independent.

Related work

  • Companion: #1996, caller-controlled aggregation budgets. That issue addresses when to stop fetching; this issue addresses what to do with malformed entries.
  • #1993 motivates replacing the Skills-specific partial-result helpers with a consistent cross-SDK design.
  • #1645 records the page-level caching-hint decisions that any new result shape should preserve.

[!NOTE]
This issue was drafted with GitHub Copilot.

Dominant language
C#
Stars
4.6k
Forks
849
Avg merge
1d 16h
Merged PRs (30d)
24

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

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.

More from modelcontextprotocol/csharp-sdk

All issues in modelcontextprotocol/csharp-sdk

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.