[DOCS] Logic Flaw: Mandatory streaming input (async generators) for Custom MCP Tools

Documentation Type

Unclear/confusing documentation

Documentation Location

docs/en/agent-sdk/custom-tools.md

Section/Topic

Section: "Using Custom Tools" Subsection: The <Note> callout regarding input streaming requirements.

Current Documentation

Important: Custom MCP tools require streaming input mode. You must use an async generator/iterable for the prompt parameter - a simple string will not work with MCP servers.

What's Wrong or Missing?

This statement introduces a significant logic flaw and a developer experience friction point:

1. Contradiction with Function Signatures: In both the TypeScript (typescript.md) and Python (python.md) reference files, the query() function explicitly allows prompt to be a string. There is no mention in the type definitions that the string type is invalidated if the mcpServers option is present.
2. Architectural Inconsistency: Standard agentic patterns typically iterative on the response loop, but allow the initial prompt to be a static string. If the SDK requires the user to wrap a single question in an async generator just to use a custom tool, it suggests a technical limitation (e.g., initialization order or internal piping) that is not explained.
3. Confusion of "Input" vs "Output" Streaming: Typically, MCP interactions require output streaming (to process tool calls as they happen). This note claims the input prompt must be a stream, which is counter-intuitive for one-off automated tasks.

Suggested Improvement

1. Technical Clarification: If this is a hard technical requirement, explain why a static string is incompatible with the MCP registry.
2. Type Warning: If it is required, the primary API references for query() in docs/en/agent-sdk/typescript.md and docs/en/agent-sdk/python.md must be updated to include a warning: "Note: If using mcpServers, the prompt parameter must be an AsyncIterable/generator."
3. Simplify Examples: If this is actually a documentation error (i.e., a static string does work for the first turn), remove the warning and update the "Using Custom Tools" example to show a simple string for readability.

Suggested text if the requirement is true:

"Note: Due to the lifecycle of in-process MCP servers, query() must be initiated using an async generator for the prompt argument. Static strings do not currently support the tool-discovery handshake required for custom SDK servers."

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: docs/en/agent-sdk/typescript.md shows prompt: string | AsyncIterable<SDKUserMessage>;.
• Developer Impact: Requiring an async generator for a simple question like "What is the weather?" (as seen in the example) increases boilerplate significantly for simple automation scripts.
• Example Inconsistency: The "Basic Configuration" section in mcp.md shows a query() example where the prompt is a string ("List files in my project"), yet it passes an mcpServers object. This directly contradicts the "Important" note in custom-tools.md.