Skip to content

docs(client): ClientSession documents only the input-required kwargs, not its mandatory parameters #3846

Open

Description

@lxcxjxhx

What is wrong

ClientSession.read_resource (src/mcp/client/session.py, docstring at 933) has a Google-style Args: block that lists only the three optional input-required kwargs:

documented in Args: ['input_responses', 'request_state', 'allow_input_required']
real parameters   : ['uri', 'input_responses', 'request_state', 'meta', 'allow_input_required']
UNDOCUMENTED      : ['uri', 'meta']

uri is the only parameter without a default, so the rendered API reference documents the optional arguments and hides the mandatory one. meta is undocumented as well.

The higher-level Client.read_resource (src/mcp/client/client.py:662,666) documents both correctly, so this looks like drift confined to the session layer rather than an intentional omission.

Minimal reproduction

import inspect
from mcp.client.session import ClientSession

print(inspect.signature(ClientSession.read_resource))
# (uri: AnyUrl, input_responses: ... = None, request_state: ... = None,
#  meta: ... = None, allow_input_required: bool = False) -> ReadResourceResult

Scope of the drift

The same pattern appears on three neighbouring methods in the same class, measured the same way on main — every one of them documents the input-required kwargs and nothing else, which suggests the block was written once and copied:

Method Documented in Args: Actually accepted
send_request (l. 540) metadata request, result_type, request_read_timeout_seconds, metadata, progress_callback
call_tool (l. 1052) input_responses, request_state, allow_input_required, allow_claimed name, arguments, read_timeout_seconds, progress_callback, input_responses, request_state, meta, allow_input_required, allow_claimed
get_prompt (l. 1217) input_responses, request_state, allow_input_required name, arguments, input_responses, request_state, meta, allow_input_required

call_tool is the most visible case: name and arguments are the two parameters every caller passes and neither is documented.

Proposed fix

Add the undocumented parameters to each Args: block, reusing the wording already used in the Client layer where the same parameter appears. Docstring-only, one file, no behaviour change; ruff check and ruff format --check pass on the file.

I am proposing this as one issue, because the four blocks share a cause and the fix is one file. Say the word if you would rather take read_resource alone and file the rest separately, and I will split it.

Willing to open a PR?

Yes — assign this to me (or label it help wanted) and I'll send it. I've read the intake gate and will include Fixes #<this> plus the AI-assistance disclosure the contributing guide asks for.

Activity

  1. media-ctrl commented on Nov 10, 2026

    @media-ctrl
  2. lxcxjxhx commented on Nov 11, 2026

    @lxcxjxhx
    Author

    I wrote the patch for this: #3848 (closed by require-linked-issue because I am not assigned here — it reopens on its own if a maintainer assigns this issue). The branch is lxcxjxhx:docs/session-args, one commit, 14 lines added, docstrings only.

    What it does, in case it saves someone the pass:

    Method Added
    send_request request, result_type, request_read_timeout_seconds, progress_callback
    read_resource uri, meta
    call_tool name, arguments, read_timeout_seconds, progress_callback, meta
    get_prompt name, arguments, meta

    On the overload question from the earlier comment: mkdocs.yml sets no show_overloads, so mkdocstrings renders the overload signatures and takes the docstring from the implementation — the blocks belong on the implementation, and duplicating them onto the four @overload stubs would be four copies of the same text.

    Verification: AST comparison against the previous head is identical with docstrings excluded; parsing the module with ast shows every parameter of the four methods now appears in its Args: block; pytest tests/client/test_session.py → 94 passed; ruff check and ruff format --check pass.

    I did not add the walk-the-methods test that was suggested — that is a test-suite change and I would rather keep this to the docstrings unless you want both in one place.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions