Returns the recorded payment and fulfillment states for one order owned by the connected account, with its timeline and available provider evidence. Fax confirmation concerns transmission to the receiving machine; mail delivery states reflect provider-reported milestones. Read-only; does not change, cancel or resend the order.
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes |
Changes observed during successful MCP inspections.
Output schema / (root)Previous value: -{
- "$schema": "https://json-schema.org/draft/2020-12/schema",
- "anyOf": [
- {
- "additionalProperties": false,
- "properties": {
- "addressWarnings": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "address": {
- "additionalProperties": false,
- "properties": {
- "address1": {
- "type": "string"
- },
- "address2": {
- "type": "string"
- },
- "city": {
- "type": "string"
- },
- "country": {
- "type": "string"
- },
- "email": {
- "type": "string"
- },
- "fax": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "phone": {
- "type": "string"
- },
- "postalCode": {
- "type": "string"
- },
- "state": {
- "type": "string"
- }
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "code": {
- "enum": [
- "address_unit_required",
- "address_unverified"
- ]
- },
- "message": {
- "type": "string"
- },
- "role": {
- "enum": [
- "recipient",
- "sender"
- ]
- }
- },
- "required": [
- "role",
- "code",
- "message",
- "address"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "amountCents": {
- "minimum": 0,
- "type": "integer"
- },
- "canCancel": {
- "type": "boolean"
- },
- "checkoutUrl": {
- "anyOf": [
- {
- "format": "uri",
- "type": "string"
- },
- {
- "type": "null"
- }
- ]
- },
- "createdAt": {
- "type": "string"
- },
- "currency": {
- "type": "string"
- },
- "document": {
- "additionalProperties": false,
- "properties": {
- "bytes": {
- "maximum": 10485760,
- "minimum": 1,
- "type": "integer"
- },
- "id": {
- "minLength": 1,
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "pages": {
- "maximum": 50,
- "minimum": 1,
- "type": "integer"
- },
- "sha256": {
- "pattern": "^[a-f0-9]{64}$",
- "type": "string"
- }
- },
- "required": [
- "id",
- "name",
- "pages",
- "bytes",
- "sha256"
- ],
- "type": "object"
- },
- "evidence": {
- "description": "Provider evidence as stored; its structure depends on the historical delivery provider."
- },
- "fulfillmentStatus": {
- "type": "string"
- },
- "handwritten": {
- "additionalProperties": false,
- "properties": {
- "cardId": {
- "minLength": 1,
- "type": "string"
- },
- "cardImageUrl": {
- "format": "uri",
- "type": "string"
- },
- "cardName": {
- "type": "string"
- },
- "fontId": {
- "minLength": 1,
- "type": "string"
- },
- "fontImageUrl": {
- "format": "uri",
- "type": "string"
- },
- "fontLabel": {
- "type": "string"
- },
- "message": {
- "type": "string"
- },
- "previewKind": {
- "const": "design_and_style_samples"
- },
- "recipient": {
- "additionalProperties": false,
- "properties": {
- "address1": {
- "type": "string"
- },
- "address2": {
- "type": "string"
- },
- "city": {
- "type": "string"
- },
- "country": {
- "type": "string"
- },
- "email": {
- "type": "string"
- },
- "fax": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "phone": {
- "type": "string"
- },
- "postalCode": {
- "type": "string"
- },
- "state": {
- "type": "string"
- }
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "sender": {
- "additionalProperties": false,
- "properties": {
- "address1": {
- "type": "string"
- },
- "address2": {
- "type": "string"
- },
- "city": {
- "type": "string"
- },
- "country": {
- "type": "string"
- },
- "email": {
- "type": "string"
- },
- "fax": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "phone": {
- "type": "string"
- },
- "postalCode": {
- "type": "string"
- },
- "state": {
- "type": "string"
- }
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "stampName": {
- "type": "string"
- },
- "stampOptionId": {
- "minimum": 0,
- "type": "integer"
- },
- "wishes": {
- "type": "string"
- }
- },
- "required": [
- "cardId",
- "cardName",
- "cardImageUrl",
- "fontId",
- "fontLabel",
- "fontImageUrl",
- "message",
- "wishes",
- "sender",
- "recipient",
- "previewKind",
- "stampOptionId",
- "stampName"
- ],
- "type": "object"
- },
- "id": {
- "minLength": 1,
- "type": "string"
- },
- "options": {
- "additionalProperties": true,
- "type": "object"
- },
- "paymentStatus": {
- "type": "string"
- },
- "recipient": {
- "additionalProperties": false,
- "properties": {
- "address1": {
- "type": "string"
- },
- "address2": {
- "type": "string"
- },
- "city": {
- "type": "string"
- },
- "country": {
- "type": "string"
- },
- "email": {
- "type": "string"
- },
- "fax": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "phone": {
- "type": "string"
- },
- "postalCode": {
- "type": "string"
- },
- "state": {
- "type": "string"
- }
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "refundedCents": {
- "minimum": 0,
- "type": "integer"
- },
- "sender": {
- "additionalProperties": false,
- "properties": {
- "address1": {
- "type": "string"
- },
- "address2": {
- "type": "string"
- },
- "city": {
- "type": "string"
- },
- "country": {
- "type": "string"
- },
- "email": {
- "type": "string"
- },
- "fax": {
- "type": "string"
- },
- "name": {
- "type": "string"
- },
- "phone": {
- "type": "string"
- },
- "postalCode": {
- "type": "string"
- },
- "state": {
- "type": "string"
- }
- },
- "required": [
- "name"
- ],
- "type": "object"
- },
- "service": {
- "description": "Current or historical service identifier; reads do not enable new orders.",
- "type": "string"
- },
- "timeline": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "createdAt": {
- "type": "string"
- },
- "id": {
- "minLength": 1,
- "type": "string"
- },
- "message": {
- "type": "string"
- },
- "type": {
- "type": "string"
- }
- },
- "required": [
- "id",
- "type",
- "message",
- "createdAt"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "updatedAt": {
- "type": "string"
- }
- },
- "required": [
- "id",
- "service",
- "amountCents",
- "refundedCents",
- "currency",
- "paymentStatus",
- "fulfillmentStatus",
- "createdAt",
- "updatedAt",
- "recipient",
- "sender",
- "options",
- "addressWarnings",
- "timeline",
- "canCancel"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "error": {
- "additionalProperties": false,
- "properties": {
- "code": {
- "minLength": 1,
- "type": "string"
- },
- "details": {
- "additionalProperties": false,
- "properties": {
- "addressRole": {
- "enum": [
- "recipient",
- "sender"
- ]
- },
- "canSendAsEntered": {
- "type": "boolean"
- }
- },
- "required": [
- "addressRole",
- "canSendAsEntered"
- ],
- "type": "object"
- },
- "message": {
- "type": "string"
- }
- },
- "required": [
- "code",
- "message"
- ],
- "type": "object"
- }
- },
- "required": [
- "error"
- ],
- "type": "object"
- }
- ],
- "type": "object"
-}New value: +nullOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "addressWarnings": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "address": {
+ "additionalProperties": false,
+ "properties": {
+ "address1": {
+ "type": "string"
+ },
+ "address2": {
+ "type": "string"
+ },
+ "city": {
+ "type": "string"
+ },
+ "country": {
+ "type": "string"
+ },
+ "email": {
+ "type": "string"
+ },
+ "fax": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "phone": {
+ "type": "string"
+ },
+ "postalCode": {
+ "type": "string"
+ },
+ "state": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "code": {
+ "enum": [
+ "address_unit_required",
+ "address_unverified"
+ ]
+ },
+ "message": {
+ "type": "string"
+ },
+ "role": {
+ "enum": [
+ "recipient",
+ "sender"
+ ]
+ }
+ },
+ "required": [
+ "role",
+ "code",
+ "message",
+ "address"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "amountCents": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "canCancel": {
+ "type": "boolean"
+ },
+ "checkoutUrl": {
+ "anyOf": [
+ {
+ "format": "uri",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "createdAt": {
+ "type": "string"
+ },
+ "currency": {
+ "type": "string"
+ },
+ "document": {
+ "additionalProperties": false,
+ "properties": {
+ "bytes": {
+ "maximum": 10485760,
+ "minimum": 1,
+ "type": "integer"
+ },
+ "id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "pages": {
+ "maximum": 50,
+ "minimum": 1,
+ "type": "integer"
+ },
+ "sha256": {
+ "pattern": "^[a-f0-9]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "name",
+ "pages",
+ "bytes",
+ "sha256"
+ ],
+ "type": "object"
+ },
+ "evidence": {
+ "description": "Provider evidence as stored; its structure depends on the historical delivery provider."
+ },
+ "fulfillmentStatus": {
+ "type": "string"
+ },
+ "handwritten": {
+ "additionalProperties": false,
+ "properties": {
+ "cardId": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "cardImageUrl": {
+ "format": "uri",
+ "type": "string"
+ },
+ "cardName": {
+ "type": "string"
+ },
+ "fontId": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "fontImageUrl": {
+ "format": "uri",
+ "type": "string"
+ },
+ "fontLabel": {
+ "type": "string"
+ },
+ "message": {
+ "type": "string"
+ },
+ "previewKind": {
+ "const": "design_and_style_samples"
+ },
+ "recipient": {
+ "additionalProperties": false,
+ "properties": {
+ "address1": {
+ "type": "string"
+ },
+ "address2": {
+ "type": "string"
+ },
+ "city": {
+ "type": "string"
+ },
+ "country": {
+ "type": "string"
+ },
+ "email": {
+ "type": "string"
+ },
+ "fax": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "phone": {
+ "type": "string"
+ },
+ "postalCode": {
+ "type": "string"
+ },
+ "state": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "sender": {
+ "additionalProperties": false,
+ "properties": {
+ "address1": {
+ "type": "string"
+ },
+ "address2": {
+ "type": "string"
+ },
+ "city": {
+ "type": "string"
+ },
+ "country": {
+ "type": "string"
+ },
+ "email": {
+ "type": "string"
+ },
+ "fax": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "phone": {
+ "type": "string"
+ },
+ "postalCode": {
+ "type": "string"
+ },
+ "state": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "stampName": {
+ "type": "string"
+ },
+ "stampOptionId": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "wishes": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "cardId",
+ "cardName",
+ "cardImageUrl",
+ "fontId",
+ "fontLabel",
+ "fontImageUrl",
+ "message",
+ "wishes",
+ "sender",
+ "recipient",
+ "previewKind",
+ "stampOptionId",
+ "stampName"
+ ],
+ "type": "object"
+ },
+ "id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "options": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "paymentStatus": {
+ "type": "string"
+ },
+ "recipient": {
+ "additionalProperties": false,
+ "properties": {
+ "address1": {
+ "type": "string"
+ },
+ "address2": {
+ "type": "string"
+ },
+ "city": {
+ "type": "string"
+ },
+ "country": {
+ "type": "string"
+ },
+ "email": {
+ "type": "string"
+ },
+ "fax": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "phone": {
+ "type": "string"
+ },
+ "postalCode": {
+ "type": "string"
+ },
+ "state": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "refundedCents": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "sender": {
+ "additionalProperties": false,
+ "properties": {
+ "address1": {
+ "type": "string"
+ },
+ "address2": {
+ "type": "string"
+ },
+ "city": {
+ "type": "string"
+ },
+ "country": {
+ "type": "string"
+ },
+ "email": {
+ "type": "string"
+ },
+ "fax": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "phone": {
+ "type": "string"
+ },
+ "postalCode": {
+ "type": "string"
+ },
+ "state": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ },
+ "service": {
+ "description": "Current or historical service identifier; reads do not enable new orders.",
+ "type": "string"
+ },
+ "timeline": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "createdAt": {
+ "type": "string"
+ },
+ "id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "message": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "type",
+ "message",
+ "createdAt"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "updatedAt": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "service",
+ "amountCents",
+ "refundedCents",
+ "currency",
+ "paymentStatus",
+ "fulfillmentStatus",
+ "createdAt",
+ "updatedAt",
+ "recipient",
+ "sender",
+ "options",
+ "addressWarnings",
+ "timeline",
+ "canCancel"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "error": {
+ "additionalProperties": false,
+ "properties": {
+ "code": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "details": {
+ "additionalProperties": false,
+ "properties": {
+ "addressRole": {
+ "enum": [
+ "recipient",
+ "sender"
+ ]
+ },
+ "canSendAsEntered": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "addressRole",
+ "canSendAsEntered"
+ ],
+ "type": "object"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "error"
+ ],
+ "type": "object"
+ }
+ ],
+ "type": "object"
+}Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds real value beyond that: it enumerates what the returned state comprises (timeline, provider evidence) and clarifies that fax confirmation is transmission-level while mail states are provider-reported milestones. The 'does not change, cancel or resend' clause partly restates annotations but usefully rules out the resend side effect an agent might otherwise assume.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core purpose before the auxiliary semantics. The read-only disclaimer is slightly redundant against the annotations, costing a little efficiency, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing returns, and it does so at a high level (payment/fulfillment states, timeline, provider evidence). Combined with annotations covering the safety profile and a single required param, an agent has enough to invoke it correctly; only the orderId format is left unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter (orderId) and schema description coverage is 0%, so the schema gives no format hints. The description does not explain the orderId format, but it does add a meaningful constraint — the order must be owned by the connected account — which is scope information the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (returns) and resource (recorded payment and fulfillment states for one order) and scopes it to an order owned by the connected account. It further disambiguates what 'status' actually includes (timeline, provider evidence) and distinguishes fax vs mail semantics. It does not, however, explicitly differentiate itself from sibling tools like postedly_orders or postedly_document_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: fetch this when you need the state of a single order the connected account owns. There is no explicit when-to-use/when-not guidance and no pointer to the sibling tools (e.g., postedly_orders for listing) that would help an agent route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.