ego-mcp presents a specialised agent-scaffolding system with 16 tools. Naming follows verb-noun convention consistently (wake_up, attune, remember, recall, etc.). However, definition quality is uneven: most tools have brief descriptions (10 - 50 chars), several lack parameter descriptions, and output schemas are not documented. Tool composition is thematically coherent (memory, relationship, desire management) but lacks the depth of error guidance and field documentation expected in production systems. The server uses STDIO transport (hard cap 50), which prevents remote accessibility. Input schemas are present and reasonably structured for most tools, but parameter descriptions are sparse or missing, particularly for complex polymorph tools like `curate_notions` and `configure_desires`. The distinction between tool risks (READ_ONLY, WRITE, DESTRUCTIVE) is declared but not reflected in tool annotations.
Tools (16)
attuneread onlysource verified70/100
Check emotional state, desires, and current interests.
configure_desireswritesource verified62/100
View or configure desire settings.
consider_themread onlysource verified63/100
Think about someone.
consolidatewritesource verified73/100
Run consolidation.
create_episodewritesource verified70/100
Create an episode.
curate_notionswritesource verified63/100
Review and curate your notions: list, merge, relabel, delete, or manage meta_fields.
Parameter descriptions are missing or trivial for many tools. update_self field parameter lacks description of valid field names. configure_desires emergent_id, quality parameters have minimal context. This forces LLMs to guess parameter semantics.
Document return schemas for all 16 tools. Add 'Returns' section to each tool docstring specifying field names, types, and semantics. E.g., remember() should document that it returns {memory_id: string, created_at: ISO8601, ...}.
Expand tool descriptions from 10 - 40 chars to 50 - 150 chars. Add WHEN-to-use clause: 'Use when the agent needs to understand the self model before deciding on actions.' Add side-effect declaration for WRITE/DESTRUCTIVE tools.
Add parameter descriptions to all parameters. For complex tools like update_self (field, value), document valid field names as a set or enum. For curate_notions and configure_desires, add per-action parameter matrices showing which params are required for each action.
Propagate risk declarations to tool annotations. Set readOnlyHint=true for READ_ONLY tools (wake_up, attune, introspect, recall, pause, get_episode). Set destructiveHint=true for destructive tools (forget). Set idempotentHint=true for idempotent tools if applicable.
Add enum value descriptions. For recall mode=['search', 'explore'], document: mode.search='Semantic vector search', mode.explore='Graph traversal from seed node'. For curate_notions action, document each action's purpose and required parameters.
Add error recovery guidance. Document what each tool returns on failure. E.g., 'recall() returns empty array if no memories match the context. Try broadening the date range or removing emotion filters.' For forget(), document that deletion is irreversible.
Add dependency hints. For recall() with mode='explore', note 'seed parameter is required when mode=explore'. For configure_desires, document that set_sentence and set_signals require desire_id.
Tool descriptions are uniformly brief (10 - 40 chars) and lack WHEN-to-use guidance. 'Start a session' (wake_up), 'Check authenticity' (pause), 'Get self-reflection materials' (introspect) do not explain prerequisites, side effects, or LLM decision logic for tool selection.
Risk annotations declared in metadata (READ_ONLY, WRITE, DESTRUCTIVE) are not propagated to tool definitions. Tool definitions lack readOnlyHint, destructiveHint, idempotentHint fields. This prevents agents from understanding safety implications of tool invocations.
Complex polymorph tools (curate_notions with 7 actions, configure_desires with 7 actions) lack per-action parameter requirement documentation. LLMs cannot determine which parameters are required for each action enum value without trial-and-error.
No error recovery guidance. Tools do not document failure modes, retryability, or next-step suggestions. If recall() returns no results or remember() fails validation, the LLM has no guidance on what to try next.
Enum parameters lack descriptions for individual enum values. introspect focus enum has ['default', 'network'] but no explanation of what each mode returns or when to use it. recall mode enum ['search', 'explore'] and seed parameter dependency are undocumented.
introspectrecallcurate_notionsconfigure_desires
Add usage examples in descriptions. Not sample values, but action intent: 'Useful for saving experiences after important events, e.g., after learning something new or resolving a conflict.'
Consider splitting polymorph tools. configure_desires with 7 actions could become show_desire, set_desire_sentence, set_desire_signals, set_emergent_satisfaction. Each would have clearer parameter requirements and descriptions.
Add logical requirements for conditional parameters. For configure_desires, document that quality (0.5-1.0) is required only when action=set_emergent_satisfaction. Mark optional vs required per action.