Twin has 11 tools with complete input schemas and descriptions. Naming follows verb_noun convention (claim_search, session_start, etc.). Descriptions are substantive (100-250 chars), explaining WHAT and WHEN. However, parameter descriptions lack actionable constraints (no enums, ranges, or format specs). Output schemas are undocumented, LLMs cannot predict response structure. Error handling is absent from tool definitions. No tool annotations (readOnlyHint/destructiveHint). Domain/project filtering logic is sophisticated but not surfaced in parameter constraints. Missing: pagination guidance, idempotency markers, recovery hints.

• Add enum constraints to 'domain' parameter: ["work", "technical", "personal_preferences", "assistant_preferences"]. Add enum to 'type' in claim_search: ["decision", "task", "preference", "belief", "fact", "event", "procedure", "constraint"]. Add enum to 'mode' in inject_context_pack: ["compact", "explainable", "references_only"].
• Document output schemas for all tools. E.g., claim_search returns {hits: [{claim_id, summary, confidence, score}], total_count, next_cursor}. session_observe returns {suggested_context: [{claim_id, why_relevant, score}], blocked_context: [{claim_id, reason}]}.
• Add tool annotations: readOnlyHint=true for all claim_* and session_observe; destructiveHint=true for session_start, session_complete, record_feedback; idempotentHint=true for claim_get, claim_related (if safe to retry).
• Add error recovery hints to descriptions. E.g., claim_get: 'If claim not found, try claim_search() to locate it by query.' session_start: 'If domain inference fails, provide explicit domain parameter.'
• Add pagination to claim_search and claim_recent_decisions: accept 'offset' or 'cursor' parameter; return 'total_count' and 'next_cursor' in response. Document max safe limit (e.g., 'limit capped at 100 to prevent context overflow').