docs(server): document Err vs Ok(CallToolResult::error) visibility contract on ServerHandler::call_tool

[gregvirgin-ls]

Summary

Pure rustdoc PR. Documents on ServerHandler::call_tool and CallToolResult::error the distinction between the two failure modes the MCP spec defines, since they look identical at the Rust call site but reach the caller's UI very differently:

• Ok(CallToolResult::error(content)) — tool-level error. The content is rendered in the caller's MCP client; the user sees the message. The right shape for almost every "the tool didn't work" path.
• Err(McpError) — JSON-RPC protocol error. Used for METHOD_NOT_FOUND, INVALID_PARAMS (-32602), INTERNAL_ERROR (-32603), and other unroutable-request cases. Clients render these opaquely — the caller does not see the message text.

The two-failure-mode shape exists in the SDK today but isn't currently explained anywhere a handler author would notice. In practice, handlers reach for Err(...) because it looks like the natural Rust return value, and the caller sees "Tool result missing due to internal error" instead of the actual failure reason.

What this PR does

1. crates/rmcp/src/handler/server.rs — rustdoc on the call_tool method generated by server_handler_methods!. Explains both return paths, when each is correct, and points at CallToolResult::error for the worked example.
2. crates/rmcp/src/model.rs — rustdoc on CallToolResult::error with a worked example contrasting:
   • Protocol error: caller passes a missing required parameter → Err(McpError::invalid_params(...)).
   • Tool error: caller asks for a row that doesn't exist → Ok(CallToolResult::error(vec![Content::text("no such row")])).

Total diff: 81 lines added across the two files.

What this PR does NOT do

• Does not add any new types. A future change may introduce a typed ToolOutcome sum type to enforce the distinction at compile time (tracked as a separate follow-up); this PR is the lower-risk docs-only version that unblocks the class immediately.
• Does not document any dispatcher behaviour (panic catching, default timeouts, etc.). Those are the subject of separate planned work on opt-in safety semantics for call_tool; once that lands, a small follow-up doc-update PR will extend the rustdoc here to cover the new behaviour. Keeping the two changes independent so each can land on its own merit.

Behaviour change

None. Pure rustdoc addition.

Test matrix

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo doc -p rmcp --features "client,server,macros" --no-deps

(Local verification: rebased onto current upstream/main (v1.7.0+ tip); cargo build -p rmcp --features "client,server,macros" and cargo doc -p rmcp --features "client,server,macros" --no-deps both succeeded. Full test/clippy matrix above not run locally — left to CI.)

Downstream motivation

Multiple MCP-server consumers we've worked with built up the Err-everywhere pattern in their handlers, then had to do a sweep when they realised callers couldn't read their error messages. The docstring is the cheapest possible intervention that prevents that sweep for future implementations.

[gregvirgin-ls]

Heads up — CI on the latest commit (b4a8ba5, fixes the unparseable → unparsable typo flagged by crate-ci/typos on the previous run) is sitting in action_required status. Looks like the CI and CodeQL workflows need maintainer approval to run after a force-push from a first-time fork contributor; only Auto Label PR (which uses pull_request_target) ran automatically.

Happy to do anything that helps unblock — no rush, just flagging in case it's silently stuck. Thanks for taking a look.

[DaleSeo]

@gregvirgin-ls Sorry for getting to this PR late! I have two quick comments.

[DaleSeo]

As PR #894 has landed, I would limit protocol errors here to requests that cannot be routed or represented as a valid tools/call.

Suggested change

	/// ([`ErrorCode::METHOD_NOT_FOUND`]), unparsable or
	/// schema-invalid parameters ([`ErrorCode::INVALID_PARAMS`],
	/// `-32602`), or a server-internal failure that means the server
	/// cannot serve any request right now
	/// ([`ErrorCode::METHOD_NOT_FOUND`]), malformed request shape that
	/// cannot be treated as a valid `tools/call`, or a server-internal
	/// failure that means the server cannot serve any request right now

[DaleSeo]

The CallToolResult::error documentation repeats the same classification and uses an empty query as an example of a protocol error. From the perspective of someone writing a handler, an empty query is the kind of user or model correctable input error that should be returned as Ok(CallToolResult::error(...)). Otherwise, this example contradicts the current specifications.

Suggested change

	/// The server cannot route the request at all: the tool name is
	/// unknown ([`ErrorCode::METHOD_NOT_FOUND`]), the parameters cannot
	/// be parsed or fail schema validation
	/// ([`ErrorCode::INVALID_PARAMS`], `-32602`), or an infrastructure
	/// error makes the server itself unusable
	/// The server cannot route the request at all, or an infrastructure
	/// error makes the server itself unusable