AdvantageScope MCP has 4 tools with consistent verb-based naming (list_, get_, validate_). All tools have descriptions and most parameters are documented. However, output schemas are not documented in the code, responses are returned as JSON text without structured schema declarations. Parameter descriptions are present but some lack format/constraint details. Error handling returns text responses marked with isError flag but lacks recovery guidance. The server is domain-specific (FRC AdvantageScope asset configuration) with reasonable tool composition, but documentation could be stronger for downstream chaining.

• Declare explicit output schemas for each tool. Example: list_assets should document it returns {assets: [{name: string, type: AssetType, path: string, configPath: string}], total: number}. This enables LLMs to plan downstream calls (e.g., passing configPath to get_asset_config).
• Add recovery hints to error messages. When asset_type inference fails, return 'Could not determine asset type. Solutions: (1) Use standard directory naming like Field2d_MyAsset/, or (2) pass the asset_type parameter explicitly.' This matches pattern:recovery-guide.
• Document path format expectations in parameter descriptions. For file_path and base_dir, clarify: 'Absolute or relative path. Relative paths are resolved from the current working directory. Path must exist and be readable.'
• Add dependency hints in tool descriptions. For get_asset_config and validate_asset_config, add: 'To discover asset config paths, call list_assets() first with the base directory.' This guides multi-step agent planning.
• Enrich error context. When a file read fails, include the attempted path and the underlying OS error (e.g., 'ENOENT: file not found at /path/to/config.json'). This helps agents debug path issues.
• For validate_asset_config, document the error response format. Currently errors are returned as a list of strings. Define the structure: is each error a string, or an object with {field: string, message: string, severity: 'error'|'warning'}? Structured errors are easier for LLMs to parse.
• Add idempotency documentation. list_assets, get_asset_config, and validate_asset_config are all read-only and safe to retry. Add a note: 'This tool is idempotent, calling it multiple times with the same parameters is safe.'