Customer Intelligence & Segmentation

Score Customer Book (A/B/C/D)

customer_tiering

Read-only

Scores a customer book of 500 transaction rows OR FEWER into A/B/C/D tiers. Send the rows directly; this server runs the survival model (BG/NBD), spend model (Gamma-Gamma), tier migration, money layer and decision cards, and returns the full result including a per-customer ledger with explanation traces. For books LARGER than 500 rows use customer_tiering_get_engine instead — sending thousands of rows as tool arguments is slow and risks truncated JSON. Optionally accepts rep_contacts, which lets the money layer learn contact uplift from data rather than assuming it. Customer identifiers are CLEANED HERE before scoring: capitalisation, spacing, punctuation, legal-suffix and word-order variants (ACME PVT LTD / Acme Pvt. Ltd. / Acme Private Limited) are merged into one account by rule, so send the values exactly as they appear in the source and do not pre-normalise them. Anything that needs context instead of rules — 'Acme & Co' vs 'Acme Pvt Ltd', a name under two codes — comes back in identity_cleaning.review_candidates, unmerged, for you to judge from the surrounding rows and re-send via identity_overrides. Pass customer_name alongside a coded customer_id to have accounts reported by name.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`as_of`	No	Analysis date YYYY-MM-DD. Defaults to latest transaction date.
`currency`	No	ISO currency code for money display (e.g. INR, USD, EUR). No FX conversion.	USD
`rep_contacts`	No	Optional rep-activity log [{customer_id, date}, ...]. Builds touched vs untouched Markov matrices and learns contact uplift per tier (≥ 10 touched transitions). Observational, not causal.
`transactions`	Yes	Purchase rows. Each item needs customer_id, date, and amount (> 0, finite). Send customer_id exactly as the source has it: capitalisation, spacing, punctuation, legal-suffix and word-order variants are merged here by rule. Do not pre-normalise. Add customer_name when the source has a name as well as a code.
`horizon_months`	No	CLV projection horizon in months.
`currency_symbol`	No	Override display symbol (e.g. ₹, $, R$).
`identity_overrides`	No	Your judgement calls on the review_candidates a previous call reported: {raw or reported customer value -> the account it belongs to}. Spelling variants are merged automatically and need no entry here; use this only for groups the rules deliberately left separate, and only after reading the surrounding rows or asking the user.
`risk_period_months`	No	Window over which neglect churn risk is assessed.
`include_diagnostics`	No	If true, include MLE params and multi-start fit diagnostics.
`rep_queue_max_items`	No	Max length of the daily SAVE/GROW/VERIFY rep queue.
`annual_discount_rate`	No	Annual discount rate for CLV (e.g. 0.10 = 10%).
`assumed_upgrade_prob`	No	Fallback P(upgrade \| contacted). Used only when learned data from rep_contacts is insufficient for that tier.
`contact_effectiveness`	No	Fallback fraction of at-risk churn recovered by one contact. Used only when rep_contacts is missing or too sparse for that tier.
`min_customers_for_model`	No	Below this count, BG/NBD refuses to fit.
`rep_queue_min_save_revenue`	No	Ignore SAVE candidates with lifetime revenue below this.
`min_repeat_buyers_for_model`	No	Below this repeat-buyer count, BG/NBD refuses to fit.

Output Schema

TableJSON Schema

Name	Required	Description
`alerts`	No	List from the upstream customer tiering API.
`status`	Yes	1 = success, 0 = error
`message`	No
`metadata`	No	Upstream customer tiering API payload.
`customers`	Yes	List from the upstream customer tiering API.
`decisions`	Yes	Ranked plain-language manager cards (CALL NOW / GROW / CHECK). Money, days, account names only — no P(alive) / CLV / RFM jargon.
`rep_queue`	Yes
`book_summary`	No	Upstream customer tiering API payload.
`book_exposure`	No
`uplift_targets`	No	List from the upstream customer tiering API.
`migration_model`	No
`identity_cleaning`	Yes	What the server did to the customer identifiers before scoring: which spelling variants it merged by rule, which groups it deliberately left separate for YOU to rule on (review_candidates — read the rows and decide, then re-run with identity_overrides), how names were chosen for display, and the counts before and after. Always relay the merges and the open questions; the tiers depend on them.
`money_assumptions`	No
`data_quality_report`	No	Upstream customer tiering API payload.

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: ID variants are merged server-side by rule, ambiguous identities are surfaced unmerged in review_candidates, rep_contacts learning is 'observational, not causal', and full result includes per-customer ledgers with explanation traces. No contradiction with annotations.

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?

The description is long but every paragraph earns its place: core action, size limit and sibling routing, optional rep_contacts, and the identity-cleaning workflow are all present. Some instructions repeat the schema (e.g., 'do not pre-normalise'), but the repetition is intentional emphasis rather than filler.

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 tool with 16 parameters, nested objects, and an output schema, the description is unusually complete. It covers the pipeline, the boundary condition for the sibling tool, the identity-cleaning model the agent must understand, and where ambiguous cases surface. The output schema covers return values, so further return-format detail is unnecessary.

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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for key parameters: rep_contacts learns uplift from data rather than assuming it, transaction customer_id must be sent exactly as sourced without pre-normalisation, customer_name is only for reporting labels, and identity_overrides is for judgement calls on review_candidates. This elevates it above baseline.

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 opens with a specific verb and resource: 'Scores a customer book of 500 transaction rows OR FEWER into A/B/C/D tiers.' It names the exact models run and what is returned (per-customer ledger with explanation traces), and it clearly distinguishes itself from the sibling by the 500-row boundary.

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?

Explicit when-to-use guidance is present: 'For books LARGER than 500 rows use customer_tiering_get_engine instead — sending thousands of rows as tool arguments is slow and risks truncated JSON.' It also tells agents not to pre-normalise identifiers and to use identity_overrides only after judging review_candidates, which prevents misuse.

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

All Customer Intelligence & Segmentation tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.5/5.0

Disambiguation4/5

Both tools perform the same A/B/C/D tiering workflow, but the explicit 500-row threshold and direct-vs-script delivery make them distinguishable. An agent could still misselect if it ignores the size boundary, so it is not a perfect 5.

Naming Consistency3/5

Both names share the customer_tiering prefix and use snake_case, but one is a bare action while the other appends get_engine, describing delivery mechanism rather than a distinct domain operation. The pattern is readable but not fully consistent.

Tool Count3/5

Two tools is borderline for a server whose purpose sounds broader than its actual scope. The two-path design is justified, though, since direct row submission would be impractical for large books.

Completeness4/5

The pair covers the core tiering workflow: direct scoring, large-scale script generation, identity cleaning, optional contact uplift, and result outputs. Missing pieces like override management are handled through parameters rather than separate tools, so agents are not left at a dead end.

Resources

Need Help?