portmap has 4 tools with clear, action-oriented names (portmap_scan, portmap_graph, portmap_resolve_url, portmap_findings) and reasonable descriptions (80 - 150 chars). All tools have input schemas with type definitions and parameter descriptions. However, output schemas are NOT documented, responses are JSON strings without declared field structures. Parameter descriptions are minimal (10 - 30 chars) and lack format/constraint details. No error handling guidance; tools return JSON but do not explain recovery paths. All tools are READ_ONLY, which is good for safety, but the server lacks pagination, result limits, and structured output documentation that production tools require.

• Document output schemas for all tools. For portmap_scan, declare: {type: 'object', properties: {services: {type: 'array'}, findings: {type: 'array'}, references: {type: 'array'}}, required: ['services', 'findings']}. This enables LLMs to extract and chain data.
• Expand parameter descriptions to 50 - 150 chars. Example: 'path' → 'Absolute or relative path to project root. Defaults to current working directory. Must contain package.json or vite.config.js.'
• Add error handling to tool responses. If path is invalid, return {ok: false, error: 'Path not found: /invalid/path', suggestion: 'Verify path exists and contains package.json'}. Guide LLM recovery.
• Implement pagination for portmap_findings. Add optional limit (default 20, max 100) and offset parameters. Return {findings: [...], total: 42, hasMore: true} so agents can iterate.
• Add tool annotations (readOnlyHint: true) to all tools in server.tool() registration to signal safety to clients and enable optimizations.