The Apache Beam MCP server has 12 tools with moderate to poor definition quality. While tool names generally follow verb_noun conventions and schemas are visible in the registry, there are significant gaps in descriptions, parameter documentation, and output schema specification. Many tools have generic or minimal descriptions (e.g., 'List available runners' is only 24 chars). Parameter descriptions are sparse, the create_job tool accepts 'pipeline_options' as a free-form object with only a brief description 'Runner-specific pipeline options', providing no guidance on structure, constraints, or valid keys. Output schemas are not documented anywhere in the provided source, making it difficult for LLMs to reason about chaining tools. The text-tokenizer tool lacks description of its return format (is it an array of tokens? an object with metadata?). Error handling is minimal, no evidence of recovery guidance, categorization of errors, or actionable error messages. Several tools (particularly the tools_router CRUD operations) operate on abstract 'tool definitions' without clear schema documentation. The server lacks tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite having a clear risk matrix in the metadata.

• Document output schemas for all tools. Use JSON Schema notation in descriptions or a separate schema section. Example for get_job: 'Returns: {job_id, status, pipeline_name, runner_type, created_at, updated_at, error_message?}'
• Expand descriptions to 50 - 150 chars with explicit WHAT/WHEN/WHY. Example: 'Cancel a running Beam pipeline job. Call this when a long-running batch job should be terminated. Returns confirmation and final job status.' (Current: 'Cancel a running job')
• Add tool annotations to the MCP server response. Mark read_only tools with readOnlyHint:true, destructive tools with destructiveHint:true, and idempotent tools with idempotentHint:true.
• Convert free-form object parameters to structured schemas. For 'pipeline_options', define a schema object with documented keys (num_workers: integer, machine_type: string, disk_size_gb: integer, etc.) or link to configuration docs.
• Add pagination to list_runners and list_tools: include limit (default 20, max 100), offset/cursor parameters, and return a total_count and next_cursor in responses.
• Implement confirmation pattern for destructive operations. Before delete_tool or cancel_job, require a 'confirm_delete: true' parameter or return an input_required response asking for confirmation.
• Add detailed error handling with recovery guidance. Example: 'if code_path does not exist, return {"error": "File not found at /path/to/code", "suggestion": "Verify the path exists and is readable. Use list_pipelines to see available code locations."}' (follows recovery-guide pattern)

Inferred effective spec: <=2025-11-25.

• Relies on Stateful initialize / Mcp-Session-Id (removed; protocol is stateless) - make each request self-contained