VA Agent API exposes 12 tools via fastapi-mcp with HTTP transport. All tools have basic names and descriptions, and most parameters include type information. However, many descriptions are generic and insufficient for LLM decision-making; output schemas are not documented; error handling provides no recovery guidance; and destructive operations lack confirmation patterns. The tool set is well-structured (single concerns, verb-noun naming) but falls short of production-grade quality due to missing schema documentation and weak parameter descriptions that do not explain WHEN to use each tool or WHAT to expect in responses.

• Add output schemas to every tool documenting the response structure. Example for get_todo_by_id: {"id": "uuid", "title": "string", "description": "string", "status": "pending|completed|archived", "collection_id": "uuid|null", "created_at": "ISO 8601 date"}
• Expand descriptions to 60-200 chars and include WHEN to use the tool. Example: 'Retrieve a single todo by its UUID. Use this after searching for a todo or when you have its exact ID. Returns the full todo object including status and collection.'
• Add pagination to get_all_todos and get_all_collections. Introduce 'limit' (default 20, max 100) and 'offset' (default 0) parameters. Document: 'Returns paginated list of todos with total count. Use offset to iterate through large collections.'
• Implement dry-run or confirmation step for delete_todo and delete_collection. Add optional 'confirm: true' parameter or return a confirmation_required response type (pattern: Multi Round-Trip Request) requiring explicit agent confirmation before executing the delete.
• Enhance error handling in get_todo_by_id, get_collection_by_id, and delete_* tools. Return structured errors: {"error": "not_found", "message": "Todo with ID xyz not found", "suggestions": ["Try calling get_all_todos() to browse available todos", "Verify the todo_id format is a valid UUID"]}
• Add a search_todos tool accepting query: string, status?: enum, collection_id?: uuid. Returns matching todos with brief summaries. Reduces need to fetch all todos.
• Document that create_todo and update_todo modify state and are idempotent only if an idempotency key is provided. Add optional 'idempotency_key' parameter to support safe retries.