Reward and gems
All MCP tools for the gem economy and the reward catalog.
The gem economy and the reward catalog. Most gem flow happens implicitly via task.create's rewardSpec and task completion; the tools below cover the manual paths and the catalog management.
gems.adjustSafe to retry
Adjust a kid's gem balance directly. High-sensitivity scope; confirm with parent before deltas > 20.
Scope: gems:adjust
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
childId | string | yes | Whose balance. |
delta | int | yes | Positive (award) or negative (deduct). |
reason | string | yes | Audit trail. Surfaces in transactions and inbox. |
Request example
{
"method": "tools/call",
"params": {
"name": "gems.adjust",
"arguments": {
"childId": "a4b9-...",
"delta": 5,
"reason": "Helped grandma with groceries"
}
}
}Returns. { childId, newBalance, transactionId }
Response example
{
"result": {
"childId": "a4b9-...",
"newBalance": 47,
"transactionId": "tx_3c..."
}
}gems.query_balance
Current gem balance per kid.
Scope: gems:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
childId | string | yes | The kid. |
Request example
{
"method": "tools/call",
"params": {
"name": "gems.query_balance",
"arguments": { "childId": "a4b9-..." }
}
}Returns. { childId, balance, asOf }
Response example
{
"result": {
"childId": "a4b9-...",
"balance": 47,
"asOf": "2026-05-23T14:02:00Z"
}
}gems.list_transactions
The full ledger. Paginated.
Scope: gems:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
childId | string | yes | Whose ledger. |
cursor / limit | various | no | Standard pagination. |
since / until | ISO datetime | no | Time range filter. |
Request example
{
"method": "tools/call",
"params": {
"name": "gems.list_transactions",
"arguments": { "childId": "a4b9-...", "limit": 20 }
}
}Returns. { items: [{ transactionId, delta, reason, source, timestamp }], nextCursor }
Response example
{
"result": {
"items": [
{
"transactionId": "tx_3c...",
"delta": 5,
"reason": "Helped grandma with groceries",
"source": "manual",
"timestamp": "2026-05-23T14:02:00Z"
}
],
"nextCursor": null
}
}reward.createSafe to retry
Add a reward to the family catalog.
Scope: reward:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | What the kid sees. |
costGems | int | yes | Price in gems. |
emoji | string | no | For the catalog tile. |
description | string | no | Notes for the kid. |
redemptionFlow | object | no | How redemption resolves. Type and parameters vary. |
Request example
{
"method": "tools/call",
"params": {
"name": "reward.create",
"arguments": {
"name": "Movie night pick",
"costGems": 25,
"emoji": "🍿",
"description": "You pick the movie this Friday."
}
}
}Returns. { rewardId }
Response example
{
"result": { "rewardId": "rw_5e..." }
}reward.update
Edit an existing reward. Partial patch.
Scope: reward:write
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
rewardId | string | yes | The reward. |
name / costGems / emoji / description / redemptionFlow | various | no | Same shapes as reward.create. |
Request example
{
"method": "tools/call",
"params": {
"name": "reward.update",
"arguments": {
"rewardId": "rw_5e...",
"costGems": 20
}
}
}Returns. { rewardId, changedFields }
Response example
{
"result": { "rewardId": "rw_5e...", "changedFields": ["costGems"] }
}reward.list
Catalog read.
Scope: reward:read
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
includeArchived | boolean | no | Default false. |
Request example
{
"method": "tools/call",
"params": {
"name": "reward.list",
"arguments": {}
}
}Returns. { items: Reward[] }
Response example
{
"result": {
"items": [
{
"rewardId": "rw_5e...",
"name": "Movie night pick",
"costGems": 20,
"emoji": "🍿"
}
]
}
}