Skip to main content
Glama

get_batch_results

Fetch the per-email results of a batch (uuid, custom_id, status, score, verdict, recommendation and mailbox per row, mailbox saying whether the mail server confirmed the mailbox itself; custom_id echoes whatever was supplied at submit), paginated with limit (default 20, cap 96) and offset; total counts the matching rows across every page. Pass recommendation (send, review, remove) or verdict (valid, risky, invalid, unknown) to read only the rows to act on, for example the addresses to remove, instead of every page; a row still in progress matches neither. Pass status (pending, queued, processing, completed, failed, canceled) to find the rows that failed or are still waiting. Rows come in submission order unless sort (score, started_at) and order (desc, asc) say otherwise. Use it once get_batch shows the batch is done, or to page through results as they arrive; for the batch totals alone use get_batch. Requires the results:read scope.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "batch_uuid": "<batch_uuid>"
    },
    "name": "get_batch_results"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoOrder by score or started_at instead of submission order (the default), for example the lowest scores first with order asc. A row without a score, or not started yet, sorts as the smallest.
limitNoNumber of results to return (API default 20, cap 96).
orderNoOrder direction with sort: desc (default) or asc.
offsetNoNumber of results to skip (default 0).
statusNoKeep only the rows in one of these statuses: pending, queued, processing, completed, failed, canceled. Use it to find the addresses that failed or are still waiting.
verdictNoKeep only the rows with one of these verdicts: valid, risky, invalid, unknown. Combined with status and recommendation using AND.
batch_uuidYesPublic batch UUID returned by submit_batch or list_batches.
recommendationNoKeep only the rows with one of these recommendations: send, review, remove. Use it to fetch just the addresses to remove or to review instead of paging through the whole batch.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / status
      Added value: +{
      +  "description": "Keep only the rows in one of these statuses: pending, queued, processing, completed, failed, canceled. Use it to find the addresses that failed or are still waiting.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "array",
      +    "null"
      +  ]
      +}
    • changedInput schema / properties / verdict / description
      Previous value: -"Keep only the rows with one of these verdicts: valid, risky, invalid, unknown. Combined with recommendation using AND."New value: +"Keep only the rows with one of these verdicts: valid, risky, invalid, unknown. Combined with status and recommendation using AND."
  2. Changed4 schema fields changed
    • addedInput schema / properties / order
      Added value: +{
      +  "description": "Order direction with sort: desc (default) or asc.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / recommendation
      Added value: +{
      +  "description": "Keep only the rows with one of these recommendations: send, review, remove. Use it to fetch just the addresses to remove or to review instead of paging through the whole batch.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "array",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / sort
      Added value: +{
      +  "description": "Order by score or started_at instead of submission order (the default), for example the lowest scores first with order asc. A row without a score, or not started yet, sorts as the smallest.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / verdict
      Added value: +{
      +  "description": "Keep only the rows with one of these verdicts: valid, risky, invalid, unknown. Combined with recommendation using AND.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "array",
      +    "null"
      +  ]
      +}
  3. First observed

TDQS

A4.6/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and mostly meets it: it discloses the scope requirement ("Requires the results:read scope"), pagination defaults and cap, that total counts matches across every page, submission-order defaults, and the non-obvious rule that in-progress rows match neither filter. It does not discuss rate limits or failure behavior, keeping it just short of 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.

Conciseness4/5

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

Front-loaded with the purpose and return shape, then filters, then ordering, then the sibling alternative and scope — a sensible ordering. It is a single dense block with heavy semicolon chaining, which costs a little scannability, but almost every clause carries information.

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 an 8-parameter read tool with no annotations and no output schema, the description covers the returned fields, pagination, total semantics, filter combination and ordering defaults, and the required scope. An agent has everything needed to call it correctly without guessing.

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, but the description adds real meaning beyond the schema: custom_id "echoes whatever was supplied at submit," mailbox reflects server confirmation of the mailbox itself, and a row in progress matches neither verdict nor recommendation. These are semantic clarifications an agent could not read off the schema alone.

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?

States a specific verb and resource ("Fetch the per-email results of a batch") and enumerates what each row contains (uuid, custom_id, status, score, verdict, recommendation, mailbox). It explicitly distinguishes itself from the sibling get_batch ("for the batch totals alone use get_batch"), so an agent can route between them without opening either schema.

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?

Gives concrete when-to-use guidance ("once get_batch shows the batch is done, or to page through results as they arrive") and names the alternative for the other case. It also explains the intended filter use cases — reading only rows to act on, or finding failed/still-waiting rows — rather than just listing parameters.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources