Skip to main content
Glama
Sign In
Sync MCP Server

Sync MCP Server

Official
by synchronicity-labs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

read a batch

batches_get
Read-onlyIdempotent

Retrieve a sync batch by ID to check its status, metrics, output URL, and per-item results; poll until completion to follow a batch you created.

Instructions

Read one sync. batch by id: its status, metrics and outputUrl, and once it is COMPLETED or FAILED, one results row per item (requestId, generation status, generationId, and outputMediaUrl or error). Use it to follow a batch you created; to find a batch id or check which batches are running use batches_list, and for one item's full generation details pass its generationId to generations_get.

With wait: true it polls for up to about 50 seconds until the batch finishes, sending progress notifications when the client asks for them. Reading a finished batch's result file can add up to 30 seconds more. Batches can take hours, so call again while it runs and never create the batch again.

results: failed keeps only FAILED or REJECTED rows, and none skips reading the file. If the file cannot be read (for example too large or too slow), resultsError says why and the batch fields are still current; download outputUrl or find the generations with generations_list instead.

Input Schema

NameRequiredDescriptionDefault
idYesThe batch id batches_create or batches_list returned.
waitNoPoll until the batch is COMPLETED or FAILED or about 50 seconds pass, then return its latest state; reading a finished batch's result file can take up to 30 seconds more. If it is still running, call again with wait: true instead of sleeping.
resultsNoOnce the batch finishes, which result rows to return: all (default), failed (FAILED or REJECTED only) or none.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.2.4
    • changedInput schema / properties / wait / description
      Previous value: -"Wait on the server until the job finishes or about 50 seconds pass, then return its latest state. If it is still running, call again with wait: true instead of sleeping."New value: +"Poll until the batch is COMPLETED or FAILED or about 50 seconds pass, then return its latest state; reading a finished batch's result file can take up to 30 seconds more. If it is still running, call again with wait: true instead of sleeping."
  2. Addedv0.1.5

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations it discloses concrete timing behavior: wait polls ~50 seconds, reading a finished result file can add up to 30 seconds, and batches may run for hours. It also describes degradation behavior (resultsError with reason, batch fields still current) and advises downloading outputUrl or using generations_list as fallbacks.

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?

Three short paragraphs, front-loaded with purpose and return shape, then polling behavior, then the results filter edge cases. Nearly every sentence carries information, though the wait/results paragraphs partly restate schema text, costing a bit of density.

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 polling read tool with an output schema, this covers everything an agent needs: conditional return shape, timeout semantics, retry guidance, and fallback paths when the result file cannot be read. Nothing material about correct invocation is left to inference.

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 baseline is 3; the description still adds meaning by tying results: failed to FAILED/REJECTED rows, explaining that none skips reading the result file (a performance hint the schema omits), and pairing the 30-second read cost with finished-batch reads. Much of the wait/results wording overlaps the schema descriptions, keeping it below a 5.

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 ("Read one sync. batch by id") and enumerates what is returned: status, metrics, outputUrl, and per-item result rows once the batch is COMPLETED or FAILED. It explicitly distinguishes itself from batches_list and generations_get, so an agent can route without opening a 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 explicit when-to-use ("follow a batch you created"), when-to-use-an-alternative (batches_list to find an id or check running batches, generations_get for one item's full details via generationId), and a negative instruction ("never create the batch again"). It also prescribes the polling loop ("call again while it runs") rather than sleeping.

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

Deploy Server

Other Tools