MyDataHub

Create an order (spends credits)

create_order

Idempotent

Spends 1 credit per complete UK record against a live machine quote from quote_order, and queues the order. It needs the quote_id and an idempotency_key to reuse on any retry, so a retry never charges twice; a flag set by a model is never consent. Where the host supports elicitation the user confirms the spend in a form or on mydatahub.emailmovers.com; otherwise an agent key must cover it within its per-order cap and monthly budget. If neither applies nothing is charged: the result is a confirmation-required error with an approval_url to give the user, so keep the quote_id; a short balance returns a top_up_url. Call get_order until the status is ready, then fetch_order_records. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

Input Schema

Name	Required	Description
`name`	No
`delivery`	No	api (fetch records), csv (signed download) and google_sheets. Default api.
`quote_id`	Yes	A live machine quote from quote_order. Without one nothing is charged.
`idempotency_key`	Yes	Any unique string, such as a V4 UUID. Reuse it when retrying the same order so it is never charged twice; a different order needs a new key.
`confirmation_token`	No	The token the approval page on mydatahub.emailmovers.com returns once the signed-in person approves. It is bound to that person (their sub), this spend (the machine quote_id, or the enrichment or push) and an expiry no later than the quote's, and it is redeemable once.

Output Schema

Name	Required	Description
`id`	Yes	Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.
`name`	No
`test`	No	A test mode order (a test key, or anyone in a demo organisation): no credits were charged, the records are invented and no licence is granted. Absent on a live order.
`status`	Yes	queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).
`failure`	No
`licence`	Yes
`records`	Yes
`cost_gbp`	Yes	The charge in GBP excluding VAT at your plan's rate.
`count_id`	Yes	The count the machine quote was priced from.
`delivery`	No
`quote_id`	Yes	The machine quote the order settled.
`ready_at`	No
`buyer_kit`	No
`field_set`	No
`created_at`	No
`receipt_url`	No	A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.
`records_url`	Yes	A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.
`confirmed_by`	Yes
`download_url`	No	302 to a single-use signed URL that lives 5 minutes.
`verification`	No	The real-time check at delivery, such as 4,102 checked, 4,071 passed.
`credits_charged`	Yes	Credits, to one decimal place: whole at 1 credit a record, fractional only where a rule is (0.1 company-only, 1.8 outright, both proposed).
`dataset_version`	No	The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.
`credits_remaining`	Yes	The balance right after this order was charged.
`validation_report`	No	Present once the order is ready.
`licence_expires_at`	Yes	When the licence ends; null for outright ownership.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 9, 2026

addedOutput schema / properties / test

Added value: +{
+  "const": true,
+  "description": "A test mode order (a test key, or anyone in a demo organisation): no credits were charged, the records are invented and no licence is granted. Absent on a live order.",
+  "type": "boolean"
+}

First observedNov 9, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true): it discloses the exact cost model (1 credit per record), the double-charge protection via idempotency_key, the elicitation/agent-key/per-order-cap branches, and the failure payloads (confirmation-required with approval_url, top_up_url on short balance). No annotation is contradicted — spend is not data destruction — though the legal-basis sentence is context rather than behavior the caller must act on.

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?

Front-loaded with the decisive fact (credit spend) and every clause tends to carry real content, but it is a dense three-sentence block mixing invocation flow, error handling, and GDPR/PECR policy. The corporate-subscribers-only sentence is domain context rather than call guidance and inflates an already long definition.

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 async, spend-incurring mutation the description covers cost, required quote, retry safety, human-confirmation requirement, the poll-then-fetch continuation, and both error exits; an output schema exists so return values need no exposition. An agent could act on this without further clarification.

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?

With 80% schema coverage the baseline is 3; the description adds the reason behind the key parameters — quote_id must be live or nothing is charged, and idempotency_key must be reused on retry but is new per distinct order. It does not mention confirmation_token or the delivery enum, leaving those to the schema.

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?

Opens with a specific verb+resource+price: spends 1 credit per complete UK record against a live machine quote and queues the order. It names the producing sibling (quote_order) and the downstream siblings (get_order, fetch_order_records), so an agent can place it in the workflow without opening another schema.

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?

Gives concrete when-to-use sequencing — call get_order until ready, then fetch_order_records — plus the branch where neither elicitation nor an agent key applies, in which case nothing is charged and the agent should keep the quote_id. It stops short of saying when to prefer quote_order over create_order, but the dependency chain is otherwise explicit.

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

All MyDataHub 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.

Resources

Need Help?