FinOpsGuard defines 12 tools with reasonable naming conventions and domain-specific descriptions, but suffers from incomplete schemas, missing parameter descriptions, and insufficient error handling guidance. Tool names follow verb_noun patterns (checkCostImpact, suggestOptimizations, etc.), which is good. However, input schemas are inferred from the request classes rather than explicitly visible in tool registration. The source code shows incomplete parameter documentation, many parameters lack detailed descriptions explaining format, constraints, or valid ranges. Output schemas are not documented anywhere in the visible code. Error handling is minimal; there's one HTTPException pattern visible but no recovery guidance. The server uses FastAPI's implicit schema generation from Pydantic models, which is better than nothing, but actual parameter constraints (min/max, enums, patterns) are not visible in the provided code. Risk annotations are present (READ_ONLY, WRITE, DESTRUCTIVE) but not formally integrated into schema definitions.

• Document output schema for each tool. Example for checkCostImpact: 'Returns {cost_impact: number, impact_summary: string, affected_resources: [{name, estimated_cost_change}], recommendations: string[]}'. Every tool needs this.
• Add explicit constraints to parameter descriptions. E.g., listRecentAnalyses should document: 'limit: integer, 1-100 (default 20). offset: integer ≥ 0 (default 0).'
• Add enums to constrained parameters. createPolicy's on_violation should declare enum: ['blocking', 'advisory'] in schema, not just mention in description.
• Implement recovery-guide pattern for errors. Instead of 'raise HTTPException(500, internal_error)', return: '{error: 'analysis_failed', reason: 'Invalid IaC syntax in Terraform', suggestion: 'Check syntax with terraform validate or run suggestOptimizations first'}'.
• Add dry-run/confirmation for deletePolicy. Split into deletePolicySuggest (returns what would be deleted, no side effects) + confirmDeletePolicy (applies the deletion). Agents can plan safely.
• Document pagination limits and cursors. Add to listRecentAnalyses description: 'Returns max 100 items. Use limit and offset for pagination. Response includes {total_count, has_more, next_offset}.'
• Clarify flushCache semantics. Rename to clearCacheData or update description to: 'Clears all cached pricing and policy data. Idempotent operation. Use before running analyses on stale pricing data. Subsequent calls will be slower until cache rebuilds.'
• Formalize tool annotations in schema instead of metadata. Each tool definition should include readOnlyHint, destructiveHint fields so clients like Claude can render warnings.