Single tool 'phpmd_analyse' has a clear verb-noun name and solid description (89 chars). Input schema is present with type and description. However, output schema is only partially documented in the return type annotation (array with exit_code, output, warm_boot, error, error_class, trace), not formally exposed in tool metadata. Parameter descriptions are minimal. Error handling returns structured objects but lacks actionable recovery guidance for LLMs. Security containment is well-implemented (path traversal checks), but the tool lacks idempotency hints and does not document when to retry vs. fail.

• Add formal output schema to tool metadata: declare fields (exit_code: int, output: string, warm_boot: bool, error?: string, error_class?: string, trace?: string) with descriptions for each.
• Expand parameter description for 'path': 'Absolute filesystem path to a PHP file or directory within the configured working directory. Must exist and be readable. Paths outside working dir are rejected for security.'
• Enhance error responses with actionable guidance: e.g., 'SecurityError: path outside working directory. Ensure path is under [working_dir].' or 'RuntimeException: [specific error]. Retry with a different file or check PHPMD configuration.'
• Add tool annotations via #[McpTool] attributes: readOnlyHint=true (tool does not modify state), idempotentHint=true (safe to retry), to guide LLM retry logic.
• Document output limits in tool description: 'Returns PHPMD analysis as JSON. Output is truncated to 100KB; very large files may be partially analyzed.'

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

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