Collections Optimizer

Collections Queue, Contact Strategy & Roll-Rate Planner

collections_optimizer

Read-only

Daily collections plan within fair-collection rules. From today's overdue accounts (account_id, balance, dpd, promises, contact counts, consents, stop flags) and optional payment history (paid, contacted, channel, recovered), contact log, monthly snapshots, agents and test results it returns: propensity to pay (L2 logistic, weight-of-evidence driver report, held-out AUC); self-cure chance and contact uplift (two models, contacted vs not, held-out Qini; rule of thumb at cold start); a call queue ranked by expected extra recovery per call within agent capacity, with the best permitted channel, call window learned from reach rates, tone tier, why, and rule checks + id on every recommendation; self-cure, deferred (earliest permitted date) and do-not-contact lists; balance-first / oldest-first comparison; Markov roll rates, forecasts and eventual write-off chance; Kaplan-Meier time to cure; Hungarian agent allocation by language, skill and success; champion-challenger split and z-test. Hard limits: India 08:00-19:00, US 08:00-21:00 and Reg F 7-in-7 and 7-day wait, cease/dispute/bankruptcy/deceased/legal/hardship never queued; policy can only tighten. Decision cards first. Up to 5,000 accounts; larger: collections_optimizer_get_engine.

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": "collections_optimizer"
  }
}

Input Schema

Name	Required	Description	Default
`l2`	No
`as_of`	No	Plan date YYYY-MM-DD (default: latest date in the data).
`agents`	No	agent_id, capacity (calls per day), languages, skills, success_rate.
`policy`	No	Stricter-only settings: call_start, call_end ('HH:MM'), max_calls_7d, max_digital_7d, post_conversation_days, allowed_channels, max_tone (1-3), utc_offset (site time zone).
`history`	No	Past accounts with the same columns plus paid (0/1), contacted (0/1), channel, recovered.
`accounts`	No	Today's overdue accounts: account_id, balance, dpd or due_date; optional broken_promises, kept_promises, calls_last_7_days, last_conversation_date, utc_offset, phone_valid, sms_ok, whatsapp_opt_in, email_valid, language, product; stop flags cease_contact, dispute, bankruptcy, deceased, legal_hold, hardship.
`max_queue`	No
`snapshots`	No	Monthly state per account: account_id, period, dpd or bucket, balance, status (paid off / written off).
`test_salt`	No		cc1
`contact_log`	No	Contact attempts: account_id, timestamp (debtor local time), channel, reached.
`jurisdiction`	No	IN (RBI) or US (FDCPA / Reg F); anything else uses the stricter combination.	IN
`test_results`	No	Champion-challenger outcomes: arm, paid, recovered.
`agent_minutes`	No	Agent minutes available today (default: sum of agents' capacity).
`blocked_dates`	No	Dates with no calls (holidays, local restrictions).
`champion_name`	No		champion
`channel_costs`	No	Cost per contact by channel: call, whatsapp, sms, email, letter.
`challenger_share`	No
`explain_accounts`	No	Account ids to explain (where they went and why).
`forecast_periods`	No
`minutes_per_call`	No
`challenger_policy`	No		balance_first
`self_cure_threshold`	No

Output Schema

Name	Required	Description
`queue`	No
`alerts`	No
`status`	Yes	1 = ok, 0 = nothing could be planned
`drivers`	No
`message`	No
`summary`	No
`deferred`	No
`metadata`	Yes
`decisions`	Yes	Plain-language cards, priority order. Relay these first.
`self_cure`	No
`roll_rates`	No
`assumptions`	No
`model_check`	No
`call_windows`	No
`explanations`	No
`do_not_contact`	No
`agent_allocation`	No
`challenger_queue`	No
`policy_comparison`	No
`champion_challenger`	No
`data_quality_report`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Annotations already mark this as a safe read-only planner, and the description adds substantial behavioral context: fair-collection limits, jurisdiction-specific call windows, Reg F constraints, stop-flag exclusions, tightening-only policy, decision cards first, and the 5,000-account cap. There is no contradiction with readOnlyHint=true or destructiveHint=false.

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 purpose is front-loaded, but the description becomes a dense semicolon-heavy run-on that enumerates outputs already covered by the output schema. It is information-rich and mostly relevant, yet poorly structured and harder to scan than necessary.

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 complex 22-parameter planning tool with an output schema, the description covers the operating context, compliance constraints, account-size limit, sibling handoff, and major input categories. The remaining gap is that several configuration parameters are left to the schema without additional semantic explanation.

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 moderate at 59%, and the description explains the main data categories and policy constraints, including accounts, history, contact logs, snapshots, agents, test results, jurisdiction, and stop flags. But many configuration parameters such as l2, max_queue, test_salt, forecast_periods, minutes_per_call, channel_costs, challenger_share, and self_cure_threshold remain unclarified in the description, matching a baseline 3.

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 description states a specific verb and resource: a daily collections plan built from overdue accounts, payment history, contact logs, snapshots, agents, and test results. It also distinguishes the tool from its sibling by naming collections_optimizer_get_engine for cases above 5,000 accounts.

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 clearly frames the tool as the daily planning path and names the sibling alternative for larger account sets. However, it does not give broader when-to-use/when-not-to-use guidance beyond the account-size handoff and embedded compliance limits.

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

All Collections Optimizer 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.