The GreyNoise MCP server presents 48 tools with generally consistent naming conventions and tool definitions. All tools follow verb_noun patterns (get_, search_, list_, create_, update_, delete_). Input schemas are defined using Zod in TypeScript with proper type annotations. However, there are significant gaps in parameter descriptions, output schema documentation, and comprehensive error handling guidance. The server uses a structured tool definition system (defineTool wrapper) that enforces consistent annotation patterns, but many tools rely on inferred schema completeness rather than explicit documentation. Schema quality is uneven, some tools have well-typed parameters, but many lack detailed constraint documentation within parameter descriptions. Error handling is present (tool-errors.ts maps HTTP status codes to user-friendly messages) but lacks recovery guidance for common failure modes. Output schemas are not explicitly documented for most tools, forcing LLMs to infer structure from API responses.

• Document output schemas for all tools using Zod or JSON Schema. Include field types, presence of pagination metadata (total_count, next_cursor), and examples of expected structures.
• Add constraint annotations to numeric and string parameters. For 'days': specify '1-365', for 'size'/'page_size': '1-100'. For format-sensitive params like 'start_time'/'end_time', require ISO 8601 in description.
• Enhance error messages with recovery paths. When API returns 403, suggest 'Check your GreyNoise plan tier or contact [email protected] to request this capability.' For 404s, offer 'Did you mean: <similar-resource>?'
• Add dry-run parameters to delete-blocklist and delete-alert. E.g., 'dry_run': true returns what would be deleted without executing. Pair with a confirmation parameter for multi-step deletions.
• Document pagination explicitly. Add 'limit' (default 20, max 100) and 'offset'/'cursor' parameters to list-blocklists, list-alerts, list-callback-ips. Return 'total_count' and 'next_cursor' in responses.
• Create batch variants: create-blocklists (array of blocklist configs), update-blocklists (array), create-alerts (array). Reduces N sequential calls to one, improving latency and token efficiency.
• Clarify tool selection in descriptions. For quick-check-ip vs lookup-ip-context, state 'Use quick-check-ip for fast classification only; use lookup-ip-context for enriched metadata (hosting, threat tags, ASN).'
• Add parameter interdependencies to descriptions. E.g., gnql-timeseries-stats should note 'interval must be day or hour; choose based on granularity needed.'

Inferred effective spec: 2025-06-18+.

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