Skip to main content
Glama

get_expense_by_id

Read-only

Read one existing expense from the authenticated user's ExpenseBot spreadsheet. Supply the exact expenseId returned by search_expenses (Receipt ID in Column Q), or the user's specified rowNumber. Never invent an identifier. Returns sheetName, rowNumber, headers, values, labeled fields, receipt_url (null if absent), and reviewExpenseUrl. It does not edit, submit, delete, share, or scan anything. Also returns Paid with context (unavailable differs from blank) and typed bookkeeping paymentStatus, never bank settlement proof.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_expense_by_id"
  }
}

Input Schema

NameRequiredDescriptionDefault
expenseIdNoExact full ExpenseBot Receipt ID from Column Q
rowNumberNo1-indexed sheet row (row 1 is headers, so ≥ 2)

Output Schema

NameRequiredDescriptionDefault
valuesNo
headersNo
labeledNo
successYes
paidWithNo
rowNumberNoResolved sheet row for the expense.
sheetNameNo
expense_idNo
receipt_urlNo
paymentStatusNo
reviewExpenseUrlNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / expense_id
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / receipt_url
      Added value: +{
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  2. Changed5 schema fields changed
    • removedOutput schema / properties / labeled / additionalProperties
      Removed value: -true
    • removedOutput schema / properties / paidWith / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / paidWith / properties
      Removed value: -{
      -  "label": {
      -    "type": "string"
      -  },
      -  "origin": {
      -    "type": "string"
      -  },
      -  "revision": {
      -    "type": "integer"
      -  },
      -  "unavailable": {
      -    "type": "boolean"
      -  }
      -}
    • removedOutput schema / properties / paymentStatus / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / paymentStatus / properties
      Removed value: -{
      -  "bankSettlementVerified": {
      -    "const": false,
      -    "type": "boolean"
      -  },
      -  "basis": {
      -    "enum": [
      -      "receipt_id_prefix"
      -    ],
      -    "type": "string"
      -  },
      -  "status": {
      -    "enum": [
      -      "paid",
      -      "unpaid",
      -      "unknown"
      -    ],
      -    "type": "string"
      -  }
      -}
  3. Changed2 schema fields changed
    • addedOutput schema / properties / paidWith
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "label": {
      +      "type": "string"
      +    },
      +    "origin": {
      +      "type": "string"
      +    },
      +    "revision": {
      +      "type": "integer"
      +    },
      +    "unavailable": {
      +      "type": "boolean"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / paymentStatus
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "bankSettlementVerified": {
      +      "const": false,
      +      "type": "boolean"
      +    },
      +    "basis": {
      +      "enum": [
      +        "receipt_id_prefix"
      +      ],
      +      "type": "string"
      +    },
      +    "status": {
      +      "enum": [
      +        "paid",
      +        "unpaid",
      +        "unknown"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  4. Changed5 schema fields changed
    • removedOutput schema / properties / expense
      Removed value: -{
      -  "additionalProperties": true,
      -  "description": "The expense record.",
      -  "type": "object"
      -}
    • addedOutput schema / properties / headers
      Added value: +{
      +  "items": {},
      +  "type": "array"
      +}
    • addedOutput schema / properties / labeled
      Added value: +{
      +  "additionalProperties": true,
      +  "type": "object"
      +}
    • addedOutput schema / properties / sheetName
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / values
      Added value: +{
      +  "items": {},
      +  "type": "array"
      +}
  5. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "expense": {
      +      "additionalProperties": true,
      +      "description": "The expense record.",
      +      "type": "object"
      +    },
      +    "reviewExpenseUrl": {
      +      "type": "string"
      +    },
      +    "rowNumber": {
      +      "description": "Resolved sheet row for the expense.",
      +      "type": "integer"
      +    },
      +    "success": {
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "success"
      +  ],
      +  "type": "object"
      +}
  6. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
      -  "additionalProperties": true,
      -  "description": "Standard ExpenseBot tool result envelope. `message` is the human-readable summary the AI cites; `data` is the structured payload (totals, breakdowns, ids, etc.). On failure, `success` is false and `error` carries a code/message/hint triple.",
      -  "properties": {
      -    "data": {
      -      "additionalProperties": true,
      -      "description": "Structured payload. Shape varies per tool — common keys: total, breakdown, comparison, sampleMeta, ids, expenseId, reportId, signupUrl, results.",
      -      "type": "object"
      -    },
      -    "error": {
      -      "additionalProperties": true,
      -      "description": "Present only when success === false.",
      -      "properties": {
      -        "code": {
      -          "type": "string"
      -        },
      -        "hint": {
      -          "type": "string"
      -        },
      -        "message": {
      -          "type": "string"
      -        }
      -      },
      -      "type": "object"
      -    },
      -    "message": {
      -      "description": "Human-readable result text. Always present on success; prefer rendering this verbatim before any further reasoning.",
      -      "type": "string"
      -    },
      -    "sampleMeta": {
      -      "additionalProperties": true,
      -      "description": "Set when the underlying dataset was truncated. isTruncated=true means the agent saw a sample of `sampleCount` of `totalCount` rows; aggregate totals are still accurate.",
      -      "properties": {
      -        "isTruncated": {
      -          "type": "boolean"
      -        },
      -        "sampleCount": {
      -          "type": "integer"
      -        },
      -        "totalCount": {
      -          "type": "integer"
      -        }
      -      },
      -      "type": "object"
      -    },
      -    "success": {
      -      "description": "False on tool errors; check before reading `data`.",
      -      "type": "boolean"
      -    }
      -  },
      -  "type": "object"
      -}New value: +null
  7. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already establish readOnly/not-destructive, so the bar is lower; the description still adds real behavioral context by enumerating the returned artifacts and warning that 'Paid' context and typed paymentStatus are bookkeeping state, not bank settlement proof. That semantic caveat is the kind of nuance annotations cannot convey.

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

Conciseness4/5

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

Front-loaded with purpose and identifier sourcing, then return shape, then exclusions — a sensible order. Slightly redundant in restating 'Receipt ID in Column Q' alongside the schema's identical wording and in listing return fields that the output schema already carries.

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?

Complete for a single-record read: identifier provenance, non-mutation scope, and output caveats are all covered, and the output schema handles the return structure. The unused optional-parameter disambiguation (ID vs row number) is the only noticeable hole.

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

Parameters5/5

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

Schema coverage is 100% and both parameters are fully documented in the schema (Receipt ID from Column Q, 1-indexed row ≥ 2), so the baseline is 3; the description goes further by enforcing 'Never invent an identifier' and tying rowNumber to a user-specified value, which is the constraint an agent most often violates.

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

Purpose5/5

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

States a specific verb and resource ('Read one existing expense from the authenticated user's ExpenseBot spreadsheet') and pins the source of the identifier to search_expenses, which cleanly separates it from the list/search siblings and from get_expense_splits.

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?

Gives clear context for use (fetch a single known expense), names how to obtain a valid ID ('expenseId returned by search_expenses'), and explicitly excludes editing, submitting, deleting, sharing, and scanning. The one gap is that both parameters are optional yet the description never says which path to prefer when the agent has both an ID and a row number.

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.