Aifeels MCP Server has moderate definition quality with several critical gaps. All 5 tools have basic descriptions (10-80 chars) and visible JSON schemas in src/aifeels/mcp/tools.py, but descriptions are significantly below the 194-char baseline for production tools, lack critical context on WHEN to use each tool, and contain no guidance on dependencies or prerequisites. Parameter descriptions are minimal or absent. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present despite clear risk levels (READ_ONLY, WRITE, REVERSIBLE) being documented in the metadata. Output schemas are not documented, callers cannot know what fields to expect. Error handling via the MCPToolHandler raises ValueError for unknown tools but provides no recovery guidance. Tool naming is reasonable (verb_noun style) but lacks specificity about the emotional state domain.
Output schemas completely undocumented. All 5 tools return structured data (visible in MCPToolHandler.handle_tool_call) but no output schema is declared. Callers cannot know what fields to expect or plan downstream tool calls. LLMs need to know what fields to expect so they can plan downstream tool calls.'
Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are missing. Metadata documents risk levels (READ_ONLY, WRITE, REVERSIBLE) but tools do not expose these hints in their definitions. LLMs cannot know which tools are safe to retry or which have side effects.
Add output schemas to all 5 tools. Expand tool definitions in get_mcp_tools() to include outputSchema key. Document the structure of each return value (e.g. get_emotional_state returns {state: {arousal: float, valence: float, ...}, last_update: ISO8601 timestamp}).
Add tool annotations. Modify tool definitions to include readOnlyHint (true for get_*), destructiveHint (true for reset_emotional_state and process_event), and idempotentHint (true for read operations). Example: {..., 'readOnlyHint': true, ...}.
Expand all descriptions to 100 - 250 chars. Include WHEN to call each tool, prerequisites, and relationships. Example for get_emotional_state: 'Retrieve current emotional state (arousal, valence, dominance). Call this before process_event to understand the baseline. Apply decay=true for temporal smoothing; false for raw values.'
Add parameter documentation for apply_decay. Clarify: 'Whether to apply exponential time decay to emotional primitives. If true, returns decayed state reflecting natural emotional dissipation over time. If false, returns raw (undecayed) state from last event. Default true.'
Enumerate valid event_name values in process_event. Replace example-based documentation with formal enum: {"enum": ["std:task_success", "std:task_failed", "std:user_input_requested", ...]}. OR document the event taxonomy with a pointer to the StandardEvents class.
Add pagination to get_state_history. Accept optional limit (default 100, max 1000) and cursor parameters. Return {history: [...], total_count: int, next_cursor: string|null}. This prevents context window exhaustion.
Descriptions are 25 - 80 chars, well below 194-char production baseline. They state WHAT each tool does but omit WHEN to call it, prerequisites, dependencies, and context. State WHAT the tool does, WHEN to use it, and any prerequisites.' Example: 'process_event' lacks explanation of valid event names, consequences, or when this tool is preferred over alternatives.
reset_emotional_state and process_event lack confirmation/dry-run pattern. Agents make mistakes, a confirm_before_execute pattern prevents catastrophic errors.' Resetting emotional state is a destructive, irreversible action but has no confirmation step.
Parameter documentation is sparse. 'apply_decay' in get_emotional_state and get_recommended_action lacks explanation of WHAT decay does, HOW it affects results, and WHEN to enable/disable it.
Naming lacks domain specificity. 'process_event' is generic; in the context of Aifeels, better names might be 'apply_event_to_emotional_state' or 'trigger_emotional_event'. Specific names like send_email or create_ticket help LLMs distinguish tools.'
process_event
Implement confirmation flow for reset_emotional_state. Support a dry_run parameter or a confirm_reset tool pattern. Example: reset_emotional_state(dry_run=true) returns what WOULD be reset; then confirm_reset_emotional_state() applies it.
Enhance error handling in MCPToolHandler. Catch invalid event names in process_event and return {success: false, error: 'Unknown event: {event_name}. Valid events: std:task_success, std:task_failed, ...', recovery: 'Check StandardEvents for valid names or call list_available_events()'}. Provide recovery guidance, not just error codes.
Add a discovery tool. Create list_available_events() to help agents discover valid event names, action recommendations, or emotional state structure.
Rename process_event to apply_event_to_emotional_state or trigger_emotional_event for clarity. Current name is too generic and does not signal domain-specific behavior.
Document chaining relationships. If get_emotional_state is often followed by process_event, state this in descriptions: 'After calling get_emotional_state, use process_event to simulate how an event would affect the current state.'
Add recovery hints to descriptions. Example: 'If you need to understand available emotions or state structure, call describe_emotional_state() first.' This guides multi-step planning.