docs: clarify Pydantic tool argument envelopes

[aritejhg]

Related to #3637. This draft clarifies the current contract; it does not implement either proposed runtime behavior or close the issue.

Motivation and Context

A tool accepting book: Book expects {"book": {...}}; passing book.model_dump() as the whole arguments object does not bind that parameter. Document the correct call shape, explain defaults and model extension fields, and point applications requiring flat wire arguments to the existing low-level Server API.

Strengthen the model-parameter schema snapshot and add a public Client round-trip test covering a defaulted model, nested extension fields, and the current behavior when model fields are sent flat.

Implicit flattening or accepting both shapes remains a maintainer design decision. Standalone FastMCP 4.0.3 reproduces the reported unexpected_keyword_argument; SDK 2.x instead ignores unmatched flat fields when the model parameter has a default. This draft preserves SDK behavior.

How Has This Been Tested?

• uv run --frozen pytest tests/docs_src/test_tools.py tests/interaction/mcpserver/test_tools.py -q — 90 passed, including public client/server round trips and existing transport/protocol coverage.
• uv run --frozen pyright — 0 errors.
• Ruff lint and formatting checks for the changed test file passed.
• Markdownlint and git diff --check passed.
• Python 3.12.11 on Windows; full SDK suite and the actual ADCP application were not run.

Breaking Changes

None. Documentation and regression coverage only; no runtime API changes.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I am assigned to the linked issue (or it is labeled help wanted, or I'm a maintainer)
• I have disclosed any AI assistance and can explain the change in my own words
• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

AI assistance: prepared with Codex. Human review remains pending; the AI-accountability checkbox is intentionally unchecked. Error-handling changes are not applicable to this documentation/test draft.

At creation, #3637 is unassigned and lacks help wanted. The contribution gate is unmet and the intake bot may close this draft. No maintainer assignment or approval is implied.

[github-actions]

This PR has been closed automatically. It's still a draft, but we close those early so you don't put in more time only to have it closed the moment you mark it ready.

This repo only keeps pull requests open when they come from a maintainer, or from a contributor a maintainer has assigned to the linked issue, and this PR doesn't link an open issue yet.

• If you're already assigned to an issue for this, add Fixes #<n> to the description and the PR will reopen on its own.
• If there's no issue yet, please open one instead: what you ran into, why it matters for your use case, and a minimal reproduction. That context is super important to us and is what we use to decide what to prioritise.
• If there's an issue but you're not assigned, add Fixes #<n> anyway so they're linked, then engage on the issue itself by confirming the repro or describing the approach you'd take. Assignment is a maintainer call based on capacity; comments that only ask to be assigned don't factor in. If you are assigned, this PR reopens automatically.

You're welcome to keep pushing commits here (just avoid force-pushing, since GitHub can't reopen a rewritten branch), but that on its own won't get the PR reviewed or the issue assigned, and realistically most auto-closed PRs stay closed. There's no need to open a new PR either way.

CONTRIBUTING.md has the full reasoning, but in short:

• We're a small team with very little capacity to review community PRs right now.
• Many recent PRs are AI-generated with little human review, and reviewing one carefully still costs a maintainer as much time as it ever did. A well-described issue is usually more useful to us than the code.

Maintainers: reopen, remove missing-issue-link, or add bypass-issue-check to override.