Skip to main content
Glama

Tokenbooks - crypto and fiat accounting and payments

Get Asset Position

get_asset_position
Read-onlyIdempotent

Summarize one cryptocurrency or token across every wallet with quantity, cost basis, market value, unrealized gain or loss, and portfolio totals. This covers wallet holdings, not all ledger accounts; request a balance-sheet report for a complete statement.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "workspaceRef": "<workspaceRef>",
      "portfolioRef": "<portfolioRef>",
      "assetRef": "<assetRef>"
    },
    "name": "get_asset_position"
  }
}

Input Schema

NameRequiredDescriptionDefault
assetRefYesAsset symbol or canonical asset id
includeSpamNoAlso match assets marked as spam
portfolioRefYesPortfolio exact name or slug
workspaceRefYesWorkspace exact name or slug

Output Schema

NameRequiredDescriptionDefault
assetYes
totalsYes
currencyYes
pricedAtNo
perWalletYes
unitPriceNo
valuationYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / properties / includeSpam
      Added value: +{
      +  "description": "Also match assets marked as spam",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / pricedAt
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / unitPrice
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / valuation
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "reason": {
      +      "type": "string"
      +    },
      +    "source": {
      +      "enum": [
      +        "PORTFOLIO_CURRENCY",
      +        "STABLECOIN_PEG",
      +        "LIVE",
      +        "LAST_CLOSE",
      +        "HISTORICAL_CLOSE"
      +      ],
      +      "type": "string"
      +    },
      +    "status": {
      +      "enum": [
      +        "PRICED",
      +        "UNAVAILABLE"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "status"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "asset",
      -  "currency",
      -  "perWallet",
      -  "totals"
      -]New value: +[
      +  "asset",
      +  "currency",
      +  "valuation",
      +  "perWallet",
      +  "totals"
      +]
  2. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "asset": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "id": {
      +          "type": "string"
      +        },
      +        "name": {
      +          "type": "string"
      +        },
      +        "symbol": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "id",
      +        "symbol",
      +        "name"
      +      ],
      +      "type": "object"
      +    },
      +    "currency": {
      +      "type": "string"
      +    },
      +    "perWallet": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "chainRef": {
      +            "type": "string"
      +          },
      +          "costBasis": {
      +            "type": "string"
      +          },
      +          "marketValue": {
      +            "type": "string"
      +          },
      +          "quantity": {
      +            "type": "string"
      +          },
      +          "unrealizedGainLoss": {
      +            "type": "string"
      +          },
      +          "walletAddress": {
      +            "type": "string"
      +          },
      +          "walletName": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "chainRef",
      +          "quantity"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "totals": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "costBasis": {
      +          "type": "string"
      +        },
      +        "marketValue": {
      +          "type": "string"
      +        },
      +        "quantity": {
      +          "type": "string"
      +        },
      +        "unrealizedGainLoss": {
      +          "type": "string"
      +        },
      +        "walletCount": {
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "quantity",
      +        "walletCount"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "asset",
      +    "currency",
      +    "perWallet",
      +    "totals"
      +  ],
      +  "type": "object"
      +}
  3. First observed

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds real value by disclosing the contents of the response (cost basis, market value, unrealized P/L, portfolio totals) and, importantly, the limitation that only wallet holdings are aggregated — a caveat an agent could otherwise misread as a full portfolio position.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences with no filler: the first states what is returned, the second states the scope limit and where to go instead. The most decision-relevant information (what you get) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need no further explanation, and the annotations plus 100% parameter coverage carry the rest. The description supplies exactly the missing piece — the aggregation scope — leaving only minor gaps such as how spam assets are treated by default.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (assetRef, portfolioRef, workspaceRef, includeSpam) are already self-documenting. The description adds the aggregation scope implied by "across every wallet" but says nothing about includeSpam's effect or the symbol-vs-canonical-id convention, so it stays at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ("Summarize") on a specific resource ("one cryptocurrency or token across every wallet") and enumerates the metrics produced: quantity, cost basis, market value, unrealized gain/loss, and portfolio totals. It also draws a scope boundary against ledger-account/balance-sheet views, which helps separate it from accounting-report siblings, though it never names a sibling tool directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear exclusion ("covers wallet holdings, not all ledger accounts") and points to the correct alternative for complete statements ("request a balance-sheet report"). That is genuine when-not guidance, but the alternative is described generically rather than mapped to a concrete sibling such as request_report_export, and there is no positive "use this when..." framing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources