Scoring
| Tool | What it does |
|---|---|
score_create | Save a finished score draft as a custom score after the user approves. The plan’s custom-score limit is enforced when it is approved. Saving never replaces an existing primary score, but when the team has no primary score for that target the new score becomes the primary automatically, so say so before asking (check score_list). Use score_set_primary only when the user asks to switch. |
score_distribution | Preview how many saved records, one list, or all records would be Excellent, Good, Fair or Not a fit under a saved score or a finished draft. Counts only, never records. |
score_draft_get | Check a score draft: still building, failed, or ready with its unsaved criteria in plain words. |
score_draft_start | Start an AI draft of a new score from a description of the ideal customer and the Context Center. Nothing is saved and no credits are used. Returns a job id to check with score_draft_get. |
score_explain_record | Explain why up to 50 people or company records got their score: each criterion matched, not matched or unknown, with the record’s own value and the importance word. Criterion detail is returned for the first 3 records; ask again with fewer records for more. |
score_get | Read one score in plain words: its criteria with importance and values, label cut-offs, status and who built it. |
score_list | List the team’s lead scores for people and companies: name, whether it is an Auto-Score or custom, which is primary, criteria count, status and the custom-score plan limit. |
score_regenerate | Rebuild the People or Companies Auto-Score from the Default Context Center after the user approves. It replaces the current Auto-Score criteria when the job finishes. |
score_set_primary | Make one score the team’s primary for its target after the user approves. The Score column, tag and filter use the primary by default. |
score_create
Save a finished score draft as a custom score after the user approves. The plan’s custom-score limit is enforced when it is approved. Saving never replaces an existing primary score, but when the team has no primary score for that target the new score becomes the primary automatically, so say so before asking (check score_list). Use score_set_primary only when the user asks to switch.
Save a finished score draft as a new custom score for the team, after the user approves. The draft comes from score_draft_start and score_draft_get. The first score saved for a target becomes its primary. Free and Starter teams can keep 2 custom scores in total, and the owner enforces that limit when the approval runs.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/score-create |
| MCP tool | score_create on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Manage scores (scoring.manage) |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
draft_job_id | string | Yes | The job id of a finished score draft, from score_draft_start. Pattern ^[a-f0-9]{32}$. |
name | string | No | Replace the drafted name. Length 0 to 60. |
thresholds | object | No | Replace the default 80, 50 and 20 label cut-offs. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
score_distribution
Preview how many saved records, one list, or all records would be Excellent, Good, Fair or Not a fit under a saved score or a finished draft. Counts only, never records.
Preview how many saved records, one list, or all records would be Excellent, Good, Fair or Not a fit under a saved score or a finished draft. Returns counts only, never records. The all-records scope is an estimate.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/score-distribution |
| MCP tool | score_distribution on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
score_oid | string | No | A saved score id. Give this or draft_job_id, not both. Pattern ^[a-fA-F0-9]{24}$. |
draft_job_id | string | No | The job id of a finished score draft. Give this or score_oid, not both. Pattern ^[a-f0-9]{32}$. |
scope | string (enum) | No | saved = the team’s saved records, list = one list, all = every record (an estimate). One of: saved, all, list. Default "saved". |
list_oid | string | No | The list id. Required for scope list and not allowed otherwise. Pattern ^[a-fA-F0-9]{24}$. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
score_draft_get
Check a score draft: still building, failed, or ready with its unsaved criteria in plain words.
Check a score draft started by score_draft_start. Returns still building, failed, or the finished unsaved draft with its criteria in plain words (criterion, importance, values). Nothing is saved.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/score-draft-get |
| MCP tool | score_draft_get on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | Manage scores (scoring.manage) |
| Confirmation | Not needed. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
job_id | string | Yes | The job id returned by score_draft_start. Pattern ^[a-f0-9]{32}$. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
score_draft_start
Start an AI draft of a new score from a description of the ideal customer and the Context Center. Nothing is saved and no credits are used. Returns a job id to check with score_draft_get.
Start an AI draft of a new score from a description of the ideal customer and the Default Context Center. Nothing is saved and no credits are debited. Returns a job id to check with score_draft_get.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/score-draft-start |
| MCP tool | score_draft_start on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Manage scores (scoring.manage) |
| Confirmation | Not needed. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
target | string (enum) | Yes | people to score contacts, company to score accounts. It cannot change once a score is saved. One of: people, company. |
description | string | Yes | The ideal customer in the user’s own words, for example VP of Sales at US software companies with 50 to 500 employees. Length 3 to 1000. |
name | string | No | An optional name for the score. It can be changed when the score is saved. Length 0 to 60. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
score_explain_record
Explain why up to 50 people or company records got their score: each criterion matched, not matched or unknown, with the record’s own value and the importance word. Criterion detail is returned for the first 3 records; ask again with fewer records for more.
Explain why up to 50 people or company records got their score. Every criterion is matched, not matched or unknown, with the record’s own value and the importance word (points for a numeric score). Criterion detail is returned for the first 3 records; every record gets its score, label and counts.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/score-explain-record |
| MCP tool | score_explain_record on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
target | string (enum) | Yes | people for contacts, company for accounts. Must match the records and the score. One of: people, company. |
records | array of object | Yes | Between 1 and 50 records of the target type, one batch. Up to 50 items. |
score_oid | string | No | Explain with this score; omit to use the team’s primary score for the target. Pattern ^[a-fA-F0-9]{24}$. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
score_get
Read one score in plain words: its criteria with importance and values, label cut-offs, status and who built it.
Read one team score in plain words: its criteria with importance and values, label cut-offs, whether it is the primary, its generation status for Auto-Scores, and who built it.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/score-get |
| MCP tool | score_get on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
score_oid | string | Yes | The score id returned by score_list. Pattern ^[a-fA-F0-9]{24}$. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
score_list
List the team’s lead scores for people and companies: name, whether it is an Auto-Score or custom, which is primary, criteria count, status and the custom-score plan limit.
List the team’s scores for people and companies: name, Auto-Score or custom, primary flag, criteria count, status, and the plan’s custom-score limit. An optional target narrows the list.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/score-list |
| MCP tool | score_list on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
target | string (enum) | No | Only scores for people or for companies; omit for both. One of: people, company. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
score_regenerate
Rebuild the People or Companies Auto-Score from the Default Context Center after the user approves. It replaces the current Auto-Score criteria when the job finishes.
Rebuild the People or Companies Auto-Score from the Default Context Center, after the user approves. The replacement happens in the background; a previously ready score stays active if the rebuild fails.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/score-regenerate |
| MCP tool | score_regenerate on https://mcp.prospeo.io |
| Effect | Deletes or removes data. |
| Credits | Free, uses no credits. |
| Permission | Manage scores (scoring.manage) |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
target | string (enum) | Yes | Which Auto-Score to rebuild. One of: people, company. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
score_set_primary
Make one score the team’s primary for its target after the user approves. The Score column, tag and filter use the primary by default.
Make one score the team’s primary for its target, after the user approves. The Score column, the tag and the Scoring filter use the primary by default. Another score can be made primary again at any time.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/score-set-primary |
| MCP tool | score_set_primary on https://mcp.prospeo.io |
| Effect | Changes data. |
| Credits | Free, uses no credits. |
| Permission | Manage scores (scoring.manage) |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
score_oid | string | Yes | The score id returned by score_list. Pattern ^[a-fA-F0-9]{24}$. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.