The orchestrator-mcp-server defines 5 tools with clear action verbs (list_, start_, get_, advance_, resume_), which is good naming. However, parameter descriptions are sparse or missing entirely, schemas are partially visible but lack detail, and output structures are not documented. The tools are well-composed for workflow orchestration (each has a single responsibility), but lack the rigor expected of production tools. Error handling is mentioned in code but not reflected in tool descriptions, so LLMs have no guidance on recovery. Descriptions themselves are adequate (30-80 chars each) but do not explain WHEN to call which tool or what the LLM should expect in return.

• Document the complete output schema for each tool. For list_workflows, specify: returns array of {name: string, description: string, ...}. For start_workflow, specify: returns {instance_id: string, status: string, next_step: string, ...}. Add these to the tool description or a separate schema document visible to the LLM.
• Expand parameter descriptions. For start_workflow's 'context' parameter, specify: 'A JSON object with initial workflow variables (e.g., {user_id: string, request_data: object}). See workflow definition for required keys.' For 'report' in advance_workflow, specify: 'A JSON object with step outcome (e.g., {success: boolean, result: object, error: string if failed})'.
• Add recovery guidance to descriptions. For advance_workflow: 'Reports the step outcome and advances the workflow. If instance_id is not found, the workflow may have completed or been terminated, call get_workflow_status to verify. Returns the next step to execute.'
• Document idempotency behavior. Add to start_workflow: 'Calling this twice with the same workflow_name and context will create two separate instances. Use instance_id to retrieve an existing workflow if unsure.'
• Add pagination to list_workflows. Accept optional parameters: limit (default 20, max 100), offset (default 0). Return {workflows: [...], total: number, offset: number} to enable discovery of large definition sets.
• Ensure get_workflow_status response includes all fields needed by advance_workflow and resume_workflow, specifically current_step_name, instance_id, and any contextual metadata. Document this dependency in tool descriptions.

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

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry