Programscape

Report a credit balance

report_balance

Records the balance a provider shows for one program the founder keeps on their Programscape plan and has marked approved: the amount left, in the unit the provider reports it (US dollars, credits or requests), when it was read, and whether the founder’s own router or their assistant reported it. Optionally sets the number under which the founder wants an email reminder, in the same unit. Returns the balance as stored on the plan, with when it was read and who reported it. It is a report, never an estimate or a total, and it is never added to other programs or set against the amount awarded. Changes nothing else on the plan. Needs the founder’s Programscape sign-in.

Input Schema

Name	Required	Description
`asOf`	No	When the balance was read from the provider, as an ISO 8601 date and time. Leave out to mean now.
`unit`	Yes	The unit the provider reports the balance in: usd, credits or requests.
`amount`	Yes	What the provider shows as left, in `unit`, exactly as reported: dollars to the cent, or a whole number of credits or requests. Never an estimate, a conversion or a sum.
`planId`	No	The selected saved plan. Required when the account has more than one plan; an omitted id never chooses the most recently updated one.
`source`	No	Who is reporting: "router" for the founder’s own credit router, "assistant" for an AI assistant the founder asked. Defaults to "assistant". Only a connection made from a program on the founder’s own computer (a loopback sign-in, as the router’s) can report as "router"; any other reports as "assistant".
`estimate`	No	Router only (0151): how long this balance lasts at the recent pace. Shown on the plan labelled as an estimate, with when it was worked out. It never sets an expiration date or a date reminder. Leave out when there is no pace yet.
`programId`	Yes	The id of a program the founder keeps on their plan and has marked approved, for example "firecrawl.startup-deal".
`lowBalanceAt`	No	Optional: the number under which the founder asked to be reminded, in the balance’s unit. Replaces the reminder number on the plan.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 25, 2026

changedInput schema / properties / planId / description

Previous value: -"Which saved plan, if the founder has more than one. Leave out for their most recent."New value: +"The selected saved plan. Required when the account has more than one plan; an omitted id never chooses the most recently updated one."

Changed2 schema fields changedOct 12, 2026

addedInput schema / properties / estimate

Added value: +{
+  "additionalProperties": false,
+  "description": "Router only (0151): how long this balance lasts at the recent pace. Shown on the plan labelled as an estimate, with when it was worked out. It never sets an expiration date or a date reminder. Leave out when there is no pace yet.",
+  "properties": {
+    "daysLeft": {
+      "description": "Whole days this balance lasts at the recent pace, as the router worked it out from its own readings.",
+      "maximum": 3650,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "workedOutAt": {
+      "description": "When the router worked it out, as an ISO 8601 date and time. Leave out to mean now.",
+      "format": "date-time",
+      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "daysLeft"
+  ],
+  "type": "object"
+}

changedInput schema / properties / source / description

Previous value: -"Who is reporting: \"router\" for the founder’s own credit router, \"assistant\" for an AI assistant the founder asked. Defaults to \"assistant\". A connection made from Claude on the web always reports as \"assistant\"."New value: +"Who is reporting: \"router\" for the founder’s own credit router, \"assistant\" for an AI assistant the founder asked. Defaults to \"assistant\". Only a connection made from a program on the founder’s own computer (a loopback sign-in, as the router’s) can report as \"router\"; any other reports as \"assistant\"."

AddedOct 12, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds materially more — that the write is scoped ('Changes nothing else on the plan'), that lowBalanceAt replaces the reminder number, that estimate never sets an expiration date, and that auth is required. It also discloses the response shape even though no output schema exists. No rate limits or failure modes are covered, so not a 5.

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?

The content is roughly the right size for an 8-parameter nested write, and the purpose is front-loaded. But it is delivered as a single dense run-on sentence with a colon-list that duplicates the unit enum verbatim, making it harder to scan than it needs to be.

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?

For a nested, non-idempotent mutation with no output schema, the description covers the essential unknowns: write scope, auth requirement, that the return value echoes stored balance plus read time and reporter, and that the estimate is display-only. Minor gaps remain around plan selection behavior and error conditions, which the schema partly covers.

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 every one of the 8 parameters (including nested estimate and lowBalanceAt) is already documented in detail. The description largely restates the schema — unit, asOf, source, reminder threshold — without adding syntax or constraints beyond it. Baseline 3 applies when the schema carries the semantics.

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 first sentence states a specific verb and resource — it records the provider-reported balance for one approved program on the founder's plan — and the later clause 'It is a report, never an estimate or a total... never added to other programs' separates it from aggregation/reporting siblings like compare_programs. No sibling is named directly, so it falls short of a 5.

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?

'Needs the founder's Programscape sign-in' states a prerequisite, and the 'never an estimate or a total, never added to other programs or set against the amount awarded' clause functions as an explicit when-not boundary against aggregation tools. It gives clear usage context but never names an alternative tool to use instead.

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

All Programscape tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Report a credit balance

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources