Claude Oracle has three read-only discovery tools with reasonably clear intent, but exhibits inconsistent schema completeness and moderate description quality. All three tools are explicitly registered with Zod schemas and descriptions, which is solid. However, parameter descriptions vary in specificity, and output schemas are not documented. Error handling returns basic text messages without guidance for recovery. Tool naming is verb-forward (search, browse, sources) and appropriate. The server handles enumerated types well for 'type' and 'sort' parameters. Key weaknesses: (1) output structure undocumented, callers don't know what fields formatSearchResults() or formatBrowseResults() produce, (2) parameter relationships underspecified (e.g., how does 'semantic' mode interact with 'limit'?), (3) error messages are generic ('Unknown error') rather than actionable.

• Document output schemas for search, browse, and sources. Specify the structure returned by formatSearchResults() (e.g., {results: [{name: string, type: string, description: string, installCommand: string}], total: number}), formatBrowseResults(), and formatSources(). This enables downstream tool chaining and LLM planning.
• Add min/max constraints to Zod schemas: .min(1).max(20) on limit parameters in search and browse tools. Remove the description text 'default: 5, max: 20' and let the schema speak for itself.
• For browse, either (a) define an enum of valid categories in the Zod schema, or (b) remove the examples from the description and add a discovery call like 'Call sources() first to see available categories' to guide LLMs toward a valid query.
• Enhance error messages with recovery hints. Example: catch (error) { const message = error instanceof Error ? error.message : 'Unknown error'; const hint = message.includes('not found') ? ' Try broadening your query or using browse().' : ''; return { content: [...], isError: true }; }
• Document the prerequisite for 'semantic' mode in search. Add to description: 'Requires SKILLSMP_API_KEY environment variable. Falls back to keyword search if not set.'
• Add explicit idempotent and safe-to-retry guidance in tool descriptions. E.g., 'This is a read-only discovery tool. Safe to retry on failure.' This guides agent retry logic.
• Consider pagination for large result sets. If browse or search can return >20 results, support offset/page parameters and return a total_count so agents know when to fetch more.