Homesage.ai MCP

Get Credit Balance

get_credit_balance

Read-only

What it returns

Your account's current API credit balance plus the plan and billing context that puts the number in context — credits_used, credits_remaining, total_credits, usage_percentage, current plan_name and subscription_status, and the renewal_date when the allowance resets. Sourced from your subscription record and live credit-usage counters; no third-party data providers involved.

When to use it

Display the user's remaining credits in your dashboard.
Poll before a batch job to check headroom — calls are free (0 credits).
Surface subscription_status to gate paid features in your UI.
Compare renewal_date to "now" to show countdown timers.

Pricing

Free. This endpoint costs 0 credits per call. Safe to poll on every page load.

Errors

Status	Meaning
401	Missing or invalid API key.
403	API key valid but account is suspended.

FAQ

Why is `credits_remaining` `null`?

Your plan is unlimited or a custom plan with no fixed per-period cap. The other balance fields are also null in that case. credits_used is always populated.

When does the balance reset?

At renewal_date. For monthly plans, that's the Stripe billing-period end. For yearly plans, the credit allowance resets monthly even though the subscription itself renews yearly — renewal_date is the next monthly reset, not the yearly one.

What if the user has no subscription at all?

plan_name, total_credits, and most other fields are null. credits_used is still populated (any credits consumed outside a subscription period are reported). subscription_status is an empty string.

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_credit_balance"
  }
}

Input Schema

Name	Required	Description	Default
No arguments

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 3, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description adds real behavior: zero-credit pricing, a 401/403 error table explaining suspended-account behavior, and null-field semantics for unlimited or unsubscribed accounts. It stops short of describing pagination or rate limits, but neither plausibly applies to a free zero-parameter endpoint.

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

Conciseness3/5

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

Headers and a table give it good front-loading, but the 'What it returns' section enumerates fields (credits_used, total_credits, plan_name, etc.) that the output schema already documents, which is redundant. The FAQ is genuinely useful for null-handling edge cases, though the yearly-vs-monthly renewal explanation runs long for a balance lookup.

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

Completeness5/5

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

For a zero-parameter read with an output schema, the definition closes the remaining gaps an agent would hit: what null means, what happens with no subscription, when the allowance resets, and which error codes indicate a bad key versus a suspended account. Nothing needed to call it correctly is missing.

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

Parameters4/5

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

There are no input parameters, so per the baseline this scores 4. The description correctly says nothing about inputs, avoiding invented arguments.

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?

The opening line states a specific verb and resource: it returns 'Your account's current API credit balance plus the plan and billing context'. This is unmistakably distinct from the property-data siblings (get_comps, get_property_info, etc.), so an agent can select it without ambiguity.

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

Usage Guidelines5/5

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

The 'When to use it' section gives four concrete scenarios (dashboard display, pre-batch headroom check, feature gating on subscription_status, renewal countdown), plus an explicit statement that polling is safe because calls cost 0 credits. No alternative tool competes for this purpose, and the description says so implicitly by being self-contained.

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

All Homesage.ai MCP tools Inspect

Try in Browser