Rationales
Rationales let you document whyyou made specific investment decisions. Whether it's explaining your portfolio strategy, wallet allocation, or a rebalancing decision, rationales help you track your reasoning over time.
✅ Try it live
MCP Tools#
AI agents can interact with Rationales through the MyHold MCP server:
| Tool | Description |
|---|---|
list-rationales | List all investment rationales, optionally filtered by entity type. |
get-portfolio-rationale | Get a portfolio's investment rationale. |
set-portfolio-rationale | Create or update a portfolio's investment rationale (Markdown supported). |
get-commit-rationale | Get the rationale for a specific portfolio commit. |
set-commit-rationale | Create or update the rationale for a specific portfolio commit. |
delete-commit-rationale | Delete the rationale for a specific portfolio commit. |
get-notification-rationale | Get a notification's investment rationale. |
set-notification-rationale | Create or update a notification's rationale (Markdown supported). |
delete-notification-rationale | Delete a notification's rationale. |
What Are Rationales?#
A rationale is a markdown-formatted note attached to:
- Portfolios: Your overall investment strategy and thesis
- Wallets: Why you organized holdings this specific way
- Portfolio Commits: The reasoning behind a rebalancing action
- Notifications: Why a notification rule was created and what action to take when it fires
Rationales support full Markdown formatting, so you can use headings, lists, bold text, links, and more to structure your notes.
Data Model#
Each rationale has the following properties:
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier for the rationale |
| entityType | enum | One of: portfolio, wallet, portfolioCommit, or notification |
| entityId | string | ID of the related portfolio, wallet, or commit |
| content | string | Markdown-formatted rationale text |
| createdAt / updatedAt | timestamp | When the rationale was created/updated |
💡 Unique constraint
✅ Strong write consistency
set-commit-rationale or set-portfolio-rationale response means the data is committed — the rationale is readable on the very next get-*-rationale call. If a read returns 404 immediately after a successful write, verify that the IDs used in both calls match exactly.Portfolio Rationales#
Portfolio rationales are perfect for documenting your high-level investment strategy, thesis, or philosophy. Think of it as a living document that evolves with your portfolio.
Portfolio rationale with markdown-formatted investment thesis
Common Use Cases#
- Investment thesis: Why you believe in these assets
- Allocation strategy: Target percentages and reasoning
- Time horizon: How long you plan to hold these positions
- Risk tolerance: Your comfort level with volatility
- Rebalancing rules: When and how you'll adjust positions
Wallet Rationales#
Wallet rationales explain why you organized coins into a specific wallet. This is useful when you have multiple wallets with different purposes or strategies.
Wallet rationale explaining DeFi experimentation strategy
Common Use Cases#
- Strategy-based: “HODLing”, “Trading”, “DeFi”, “Staking”
- Exchange-based: Track coins on different exchanges
- Risk-based: “Conservative”, “Aggressive”, “Experimental”
- Tax optimization: Separate short-term vs long-term holdings
Portfolio Commit Rationales#
When you rebalance your portfolio (via a “commit”), you can attach a rationale explaining what changed and why. This creates an audit trail of your portfolio decisions.
Commit rationale documenting rebalancing decision
Common Use Cases#
- Rebalancing: Why you adjusted allocations
- Market response: Decisions based on market conditions
- Tax harvesting: Documenting tax-loss harvesting actions
- Exit strategies: Recording when/why you sold positions
💡 Learn about commits
Notification Rationales#
Notification rationales document why a notification rule was created, what signal it captures, and what action to take when it fires. This is especially valuable for complex multi-condition rules.
Notification rationale documenting a BTC buy signal alert
Common Use Cases#
- Signal documentation: Which indicators trigger the alert and why
- Action plan: What to do when the notification fires
- Threshold reasoning: Why specific values were chosen
- Context: Market conditions or strategy this alert supports
💡 Learn about notifications
Markdown Support#
Rationales support standard Markdown syntax, allowing you to format your notes with:
| Syntax | Result |
|---|---|
**bold text** | bold text |
*italic text* | italic text |
## Heading | Heading |
- List item | • List item |
[Link](url) | Link |
`code` | code |
Best Practices#
Be Specific and Actionable#
Instead of vague notes like “Good project”, write specific reasons:
“Bitcoin is a good investment”“Bitcoin: Store of value thesis. Limited supply (21M cap), institutional adoption growing, portfolio hedge against inflation. Target 40% allocation.”Update as Things Change#
Your rationales should evolve with your strategy. When market conditions change or you learn new information, update your rationales to reflect your current thinking.
Use Markdown for Structure#
Break up long rationales with headings, lists, and formatting. This makes them easier to scan when you revisit them months later.
Track Your Decision-Making Process#
Rationales are your personal investment journal. Years later, you'll be able to look back and understand exactly why you made certain decisions—and learn from them.
Privacy & Security#
Your rationales are private and only visible to you. They are:
- Stored securely in our encrypted database
- Never shared with third parties
- Automatically deleted if you delete the parent portfolio or wallet
- Accessible only with your authenticated session
Next Steps#
Portfolios →
Learn about portfolios, wallets, staged commits, and rebalancing.
Notifications →
Document your alert rules with rationales for better decision tracking.