Skip to main content
Glama

Piloxa

by io.github.Piloxa
OverviewDiscussionsAdmin

Check what happened to a letter sent through Piloxa

get_certified_letter_status
Read-onlyIdempotent

Answers "has my letter arrived yet" for letters prepared through Piloxa IN THIS SAME CONVERSATION. Returns, for each one: who it went to, the service, the USPS tracking number once USPS has assigned one, whether USPS has accepted it, delivered it or returned it, and when each of those was recorded. Piloxa asks the print and mail provider for a fresh answer when this is called, so it is current rather than remembered. IMPORTANT AND DELIBERATE: it can only see letters this connector prepared in this conversation, because that is the only thing it can identify without a sign-in; it cannot reach a person’s other letters, letters sent from another conversation, or anybody else’s. For those, the person signs in at piloxa.com and opens the letter there. This tool is READ ONLY: it prepares nothing, mails nothing and charges nothing. A stage with no scan means no scan has been reported, which is not the same as a failed delivery — USPS sometimes records delivery late, or not at all.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
referenceNoOptional. The Piloxa reference from the letter’s email receipt, to ask about one letter instead of all of them. A reference from outside this conversation is not found, on purpose.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
foundYes
scopeYesAlways says that only this conversation’s letters are visible here.
mailedYesAlways false: this tool never mails.
chargedYesAlways false: this tool never charges.
lettersYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / letters / items / properties / transaction_state
      Added value: +{
+  "enum": [
+    "AUTHORIZED",
+    "VENDOR_ACCEPTED",
+    "MAILED",
+    "DELIVERED",
+    "RETURNED",
+    "FAILED",
+    "CANCELLED",
+    "AWAITING_APPROVAL"
+  ],
+  "type": "string"
+}
  2. Changed1 schema field changed
    • changedOutput schema / properties / letters / items / properties / service / enum
      Previous value: -[
-  "CERTIFIED",
-  "CERTIFIED_ERR",
-  "CERTIFIED_EVIDENCE"
-]New value: +[
+  "CERTIFIED",
+  "CERTIFIED_ERR",
+  "CERTIFIED_EVIDENCE",
+  "CERTIFIED_DEADLINE"
+]
  3. Changed1 schema field changed
    • changedOutput schema / properties / letters / items / properties / service / enum
      Previous value: -[
-  "CERTIFIED",
-  "CERTIFIED_ERR"
-]New value: +[
+  "CERTIFIED",
+  "CERTIFIED_ERR",
+  "CERTIFIED_EVIDENCE"
+]
  4. Added

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent and openWorld, but the description adds materially: a fresh query is made to the print/mail provider on each call (so results are current, not cached), the visibility limit is deliberate and explained (no sign-in = no access to other letters), and it warns that a missing scan stage is not equivalent to failed delivery because USPS can record late. These are real operational caveats an agent could not infer from annotations.

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?

The answer-first opening ('has my letter arrived yet') and the return-field list are well front-loaded, and each caveat is load-bearing. It is slightly padded: 'READ ONLY: it prepares nothing, mails nothing and charges nothing' restates readOnlyHint/destructiveHint already in annotations, and the caps-lock emphasis adds length without new 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 a one-optional-parameter read tool with an output schema, the description is more than sufficient: it covers scope, freshness, the sign-in fallback, and the key interpretation pitfall for status data. Nothing an agent needs to call it correctly or interpret the result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single optional 'reference' parameter is fully documented in the schema itself. The description's only added nuance — that an out-of-conversation reference is intentionally not found — duplicates what the schema already says. Baseline 3 is appropriate when the schema carries the parameter burden.

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?

The description gives a concrete verb+resource (answer whether a letter prepared through Piloxa in this conversation has arrived) and immediately enumerates the returned fields — recipient, service, USPS tracking number, acceptance/delivery/return status and timestamps. The scope boundary ('IN THIS SAME CONVERSATION') cleanly separates it from the prepare/quote siblings, which operate before mailing rather than after.

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?

It states when to call it (asking whether a Piloxa-prepared letter arrived) and, unusually, when it will not work and what to do instead ('for those, the person signs in at piloxa.com'). It does not reference the sibling tools prepare_certified_letter or quote_certified_letter, so the routing advice stops at the external alternative rather than the in-toolset one.

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

All Piloxa toolsInspect
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