Single tool with adequate schema but significant description and parameter documentation gaps. The tool definition is explicitly visible in src/plausible/query.ts with proper JSON Schema structure. However, parameter descriptions are confusing and overly verbose, violating the principle that descriptions should be 10-1024 chars and human-readable. The 'metrics' parameter description is a tab-separated wall of text (500+ chars) that would confuse LLMs during parsing. No enum constraint provided for metrics despite known valid values. Output schema is completely undocumented, LLMs cannot plan downstream actions without knowing what fields to expect from the response. Error handling is minimal (client.ts throws generic API errors with no recovery guidance). Tool naming is reasonable ('plausible_query' uses verb_noun pattern and is specific), but parameter naming could be clearer ('date_range' is acceptable but lacks type hints like 'ISO8601_date_range').

• Convert metrics parameter to enum constraint: type: 'string', enum: ['visitors', 'visits', 'pageviews', 'views_per_visit', 'bounce_rate', 'visit_duration', 'events', 'scroll_depth', 'percentage', 'conversion_rate', 'group_conversion_rate', 'average_revenue', 'total_revenue']. Move metric-specific requirement notes to a separate 'details' object or inline help text, not the main description.
• Reduce metrics description to 50-100 chars: 'Array of metric names to query (e.g., visitors, bounce_rate, conversion_rate). Check Plausible docs for metric-specific filter requirements.' Hyperlink or reference external docs for the full dependency matrix.
• Add enum for date_range OR use a discriminated union: oneOf [ { const: 'day', description: '...' }, { const: '7d', ... }, { pattern: '^\d{4}-\d{2}-\d{2}$', description: 'ISO8601 date (YYYY-MM-DD)' }, ... ].
• Document output schema in queryTool definition. Add an 'outputDescription' field (or reference spec) explaining: 'Returns Plausible analytics response with fields: {results: array[{[metric_name]: number}], pagination: {page, limit, total}}'. This lets LLMs know what to extract.
• Improve error handling in plausibleClient.query(): Check response status and throw typed errors: if (response.status === 401) throw new Error('Authentication failed. Verify PLAUSIBLE_API_KEY environment variable.'); if (response.status === 400) { const body = await response.json(); throw new Error(`Invalid query: ${body.error}. Valid metrics: [list]. Try specifying a preset date_range like '7d' or 'month'.`); }