MCPShield exposes 13 tools across CLI and HTTP API. Most tools have descriptions (10-150 chars) and input schemas with typed parameters and enums. However, several critical gaps reduce quality: (1) CLI tools (scan, scan-url, version) lack explicit schema registration in source, tool definitions are inferred from CLI argument parsing, not explicit MCP tool registration. (2) HTTP endpoints are exposed as tools but lack output schema documentation, responses are not formally specified. (3) Auth/billing tools (signup, login, checkout, webhook) mix security-sensitive operations with insufficient error guidance. (4) No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications in metadata. (5) Parameter descriptions are present but often generic (e.g., 'Output format' without explaining what each format contains). Baseline: 549 production tools average 194 chars for descriptions and 72 chars for params; MCPShield averages ~80 chars for descriptions and ~50 chars for params, below median.

• Register CLI tools explicitly as MCP tools with full schemas. Move tool definitions from typer CLI parsing to explicit MCP tool registration so they are discoverable and have formal input/output schemas.
• Document output schemas for all HTTP endpoints. Add 'returns' field to each tool definition specifying the response structure (e.g., ScanResponse with fields: findings[], metadata, summary). This enables LLMs to plan chained calls.
• Add tool annotations: mark scan/scan-url/health as readOnlyHint=true; mark signup/login/checkout/webhook as destructiveHint=true or idempotentHint=false to guide agent retry behavior.
• Remove passwords from tool parameters. Implement OAuth2 or JWT token-based auth where the agent passes a pre-authenticated token (injected server-side), not a plaintext password. Alternatively, use a separate secure credential exchange mechanism.
• Expand parameter descriptions with format/constraint details. E.g., 'severity_threshold: Minimum severity level to report (critical|high|medium|low|info). Defaults to high.' instead of just 'Minimum severity level to show (critical|high|medium|low|info).'