Heroku MCP server has 36 tools with significant quality gaps. Most tools lack detailed input schemas and parameter descriptions. Tool names follow verb_noun convention (list_apps, create_app, pg_psql) but many descriptions are minimal (7-15 chars: 'List addons', 'List teams', 'PostgreSQL psql'). Only 8 of 36 tools have descriptions exceeding 50 characters. Input schemas visible for ~12 tools (apps.ts, maintenance.ts) but most lack explicit parameter type definitions or descriptions. No output schemas documented. Error handling is basic, no recovery guidance or error classification. Security concerns: pg_credentials and pg_kill expose sensitive operations without permission gates or confirmation patterns.

• Expand all 28 minimal descriptions to 50-200 characters. Example: 'List addons' → 'List all add-ons provisioned for this app, including database, cache, and monitoring services. Returns addon name, plan, and status.'
• Document input schemas for all 24 tools lacking them. Use JSON Schema with type, description, enum, and minLength/maxLength constraints. Example for pg_kill: {"pid": {"type": "integer", "description": "PostgreSQL process ID to terminate. Obtain from pg_ps()"}}
• Add output schemas to all tools. Document returned fields, types, and which IDs are needed for chaining. Example: create_app returns {"app_id": string, "app_name": string, "region": string, "created_at": ISO8601}
• Implement confirmation pattern for destructive tools: add optional 'confirm' boolean parameter. If false/omitted, return dry-run preview. If true, execute. Example: pg_kill(pid=123, confirm=false) → 'Would terminate PID 123 (query: SELECT * FROM users). Call again with confirm=true to execute.'
• Add permission gates and scope declarations. Gate pg_credentials, pg_kill, deploy_to_heroku behind role checks. Document required scopes in tool descriptions: 'Requires: admin:database' or 'Requires: write:deployment'.