Two tools with clear names and reasonable descriptions, but significant gaps in parameter documentation and output schema specification. scan_security_headers has a well-structured input schema with URL validation via Zod, but lacks parameter descriptions in the JSON Schema itself. demo_security_snapshot has no parameters but also no documented output schema. Neither tool documents what fields the response contains, forcing LLMs to infer structure. Error handling exists but is minimal. No tool annotations (readOnlyHint, idempotentHint) despite both being read-only operations.

• Document the output schema for both tools. Specify the structure of the security snapshot response (e.g., { headers: { hsts: boolean, csp: string, ... }, redirect_chain: [...], security_txt: boolean, ... }). This enables LLMs to extract and reason about specific fields.
• Add readOnlyHint: true to both tool definitions in the ListToolsRequestSchema response. This signals to clients that these tools are safe to call without side effects and can be cached or retried freely.
• Enhance error messages with recovery guidance. For invalid URLs, suggest 'URL must start with https:// or http://'. For API errors, indicate whether the call is retryable or if the user should check the target URL.
• Add a dry_run parameter (boolean, default false) to scan_security_headers. When true, return the estimated cost without charging. This prevents accidental overspend and aligns with the confirmation-request pattern.
• Expand the 'url' parameter description to include format constraints: 'A valid HTTP(S) URL (e.g., https://example.com). Must be publicly accessible. Relative URLs and localhost are not supported.'