ShipProof exposes 3 tools with complete input schemas and descriptions, but quality is uneven. All tools are READ_ONLY and well-scoped (scan, budget, capacity). Descriptions are present (60-90 chars) but lack actionable context for LLM selection. Parameters have types and descriptions, meeting baseline requirements. However, output schemas are not documented, error handling guidance is absent, and parameter constraints (e.g., severity enums, confidence levels) lack formal validation hints. The tools follow verb_noun naming (scan, budget, capacity) but descriptions do not explain WHEN to use each tool or what distinguishes them. No tool annotations (readOnlyHint, idempotentHint) are present despite all being read-only operations.

• Document output schemas for each tool. E.g., scan returns {findings: [{id, severity, file, line, message}], incomplete: boolean, total_count: number}. This enables LLMs to extract and chain results.
• Expand tool descriptions to 100-150 chars explaining WHEN to use each. E.g., 'scan: Identify security and production-readiness issues in code. Use before budget/capacity to understand risk profile.' Distinguish tools for LLM selection.
• Formalize parameter constraints as enums in schema. Change fail_on and min_confidence to enum: ['high', 'medium', 'low']. Add min/max bounds to max_file_bytes (e.g., 1000-100000000).
• Add error handling guidance. Document that 'path not found' is user-fixable (suggest valid paths), 'scan timeout' is retryable, and 'permission denied' is fatal. Include recovery hints.
• Add tool annotations. Mark all tools with readOnlyHint: true. Mark scan with idempotentHint: true. This signals to agents which tools are safe to retry and which do not modify state.