Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@logistics-mcp track shipment SBY-1003"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Operations teams ask questions about shipments all day — "where is SBY-1042", "which route missed its SLA last month", "what would 12 kg to Makassar cost". The answers sit in a logistics system that an AI assistant cannot see. This MCP server exposes that system as nine tools, so Claude can answer from the actual data instead of from a screenshot the user pasted into the chat.
It runs out of the box against a bundled demo dataset (200 synthetic shipments across 6 cities over 3 months), so you can try every tool without credentials. Point it at your own backend by setting two environment variables.
The domain model comes from a production logistics platform I built (Next.js + Supabase, deployed on GCP). This repo contains the MCP server and a synthetic demo dataset, not the client application; no real customer names, rates, or operational data appear anywhere in it.
Claude (Desktop / Code)
| MCP, stdio
v
logistics-mcp
tool handlers <- zod-validated inputs, row/byte caps, actionable errors
|
LogisticsSource <- one interface; handlers do not know which side is active
/ \
demo source rest source
fixtures/*.json LOGISTICS_API_URL + LOGISTICS_API_TOKEN (Bearer)The demo source reads the checked-in fixture JSON. The rest source expects the upstream
contract documented below. Writes are disabled unless ALLOW_WRITES=1; in demo mode an
update_shipment_status call mutates memory only and never touches the fixture files.
Related MCP server: Logistics AI MCP
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"logistics": {
"command": "npx",
"args": ["-y", "logistics-mcp"]
}
}
}Claude Code:
claude mcp add logistics -- npx -y logistics-mcpBoth configurations need nothing else: no URL, no token, no clone. To connect your own
backend instead of the demo data, add LOGISTICS_API_URL and LOGISTICS_API_TOKEN to the
server's environment.
Recorded against the demo dataset.
You: What's the status of shipment SBY-1003?
Claude calls track_shipment and gets the public timeline:
{
"spNumber": "SBY-1003",
"events": [
{ "at": "2026-07-11T05:35:01.991Z", "status": "READY", "location": "Surabaya", "description": "Shipment registered and waiting for pickup" },
{ "at": "2026-07-11T14:35:01.991Z", "status": "PICKED_UP", "location": "Surabaya", "description": "Picked up from sender" },
{ "at": "2026-07-12T11:35:01.991Z", "status": "IN_TRANSIT", "location": "Surabaya to Yogyakarta", "description": "On the way to the destination region" },
{ "at": "2026-07-13T02:35:01.991Z", "status": "AT_HUB", "location": "Yogyakarta hub", "description": "Arrived at destination sorting hub" },
{ "at": "2026-07-13T13:35:01.991Z", "status": "OUT_FOR_DELIVERY", "location": "Yogyakarta", "description": "With the courier for final delivery" },
{ "at": "2026-07-14T21:35:01.991Z", "status": "DELIVERED", "location": "Yogyakarta", "description": "Delivered to the recipient" }
]
}You: And what would 12 kg to Makassar cost on STANDARD?
quote_shipping_rate resolves the layered rate table and shows the math:
{
"freight": 174000,
"currency": "IDR",
"breakdown": {
"pricePerKg": 14500,
"minCharge": 25000,
"appliedRule": "destination_special",
"formula": "max(ceil(12 * 14500), 25000)"
},
"alternatives": [
{ "product": "ECONOMY", "freight": 68400 },
{ "product": "EXPRESS", "freight": 312000 }
]
}Other questions the demo data supports: "which route had the worst on-time rate in June"
(delivery_performance), "what's on the next load to Surabaya" (list_manifests →
get_manifest), "show everything Kirana Textiles shipped that's still in transit"
(search_shipments), "which customers still have unpaid invoices" (list_invoices).
Tool | What it answers |
| Find shipments by status, date range, route, or customer (limit default 20, max 100) |
| Full detail: items, extra charges, total amount, status history |
| Public tracking timeline, without internal ops notes |
| Price for route + weight + product, with the winning rate rule and the math |
| Outbound loads per region and date, with counts and total weight |
| Contents of one load |
| Per-route on-time rate, average transit days, exception counts for a period |
| Customer invoices by payment status or customer, with amount and due date |
| Write. Disabled unless |
Variable | Default | Effect |
| (empty) | Empty: bundled demo dataset. Set: REST backend at this URL |
| (empty) | Bearer token for the REST backend. Required when the URL is set |
|
| Only the exact value |
|
| Per-call timeout for the data source |
|
| Responses above this are trimmed with a note on how to narrow the query |
If LOGISTICS_API_URL is set without a token, the server exits with a message naming the
missing variable. It does not fall back to demo data — a demo answer presented as
production data is worse than an error.
The rest source expects these endpoints under LOGISTICS_API_URL, all with
Authorization: Bearer <LOGISTICS_API_TOKEN>:
GET /shipments?status&from&to&origin&destination&customer&limit&offset
GET /shipments/:spNumber
GET /shipments/:spNumber/tracking
GET /rates?origin&destination
GET /manifests?region&date&limit&offset
GET /manifests/:id
GET /invoices?status&customer&limit&offset
POST /shipments/:spNumber/status { "status": "...", "note": "..." }Response shapes match the TypeScript interfaces in src/sources/types.ts.
Read-only by default. The single write tool stays off unless ALLOW_WRITES=1, and when
it is off the tool says how to enable it instead of failing with a generic error.
No credentials in the repo and no credential defaults in code. The token comes from the
environment and is sent only to LOGISTICS_API_URL.
Tool errors return sentences the model can act on ("no shipment matches SBY-9999; check the number or use search_shipments"), not stack traces or raw upstream responses.
List responses are capped in rows and in bytes, so one tool call cannot flood the client's context window.
stdio transport only; the server opens no network listener of its own.
npm install
npm run build # tsc
npm test # vitest, runs against the demo dataset
npm run generate:fixtures # regenerate fixtures/data deterministicallyfixtures/generate.ts uses a fixed seed; regeneration must produce byte-identical output.
If it does not, the generator picked up nondeterminism — fix the generator, never hand-edit
the JSON. The demo-data review checklist in .claude/agents/demo-data-reviewer.md covers
the consistency rules the dataset must satisfy (chronology, rate math, cross-file
references).
The .claude/ setup is part of the repo's workflow, not decoration: a review subagent
(agents/demo-data-reviewer.md), a fixture-check skill (skills/check-fixtures/), and two
hooks wired in settings.json — hooks/no-stdout-log.sh keeps stray console.log out of
the stdio server, and hooks/no-null-bytes.sh blocks git commit when a staged text file
contains null bytes (a guard against UTF-16 output from PowerShell redirects, which once
published an empty README to npm).
stdio only; no HTTP/SSE transport.
The demo dataset is synthetic and small by design (200 shipments). Aggregations like
delivery_performance fetch up to 1000 rows and stop there.
No OAuth; the REST adapter authenticates with a static bearer token.
Aggregate delivery performance per route for a period: on-time rate, average transit days, and exception counts. Use for questions like 'which route underperformed last month'. Read-only; fetches up to 1000 shipments.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Include shipments created on or before, YYYY-MM-DD | |
| from | No | Include shipments created on or after, YYYY-MM-DD | |
| origin | No | Restrict to one origin city code | |
| destination | No | Restrict to one destination city code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature and a limit of 1000 shipments, which are key behavioral traits. No annotations are present, so description carries the full burden. Could additionally mention data freshness or empty result handling.
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?
Two sentences efficiently cover purpose, example, and behavioral notes. No redundancy or filler. Every sentence adds value.
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?
For a simple tool with no required parameters and no output schema, the description explains purpose, gives a usage example, and notes key behaviors. Could mention whether the result is a list of routes or a single aggregate, but overall sufficient.
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?
Schema description coverage is 100%, so each parameter is already well-documented. The description adds context about route-level aggregation but does not provide syntax or format details beyond the schema, meeting the baseline.
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 clearly states it aggregates delivery performance per route with specific metrics (on-time rate, average transit days, exception counts). This distinguishes it from sibling tools that focus on individual shipments (e.g., get_shipment, track_shipment).
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?
Provides a concrete usage example ('which route underperformed last month') and notes it's read-only. Does not explicitly exclude use cases or mention sibling alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Contents of one manifest: the shipments on it, total weight, and shipment count. Use after list_manifests to see what is on a specific load.
| Name | Required | Description | Default |
|---|---|---|---|
| manifest_id | Yes | Manifest id, e.g. MFST-SBY-20260714 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it returns contents, implying a read operation, but does not explicitly disclose behavioral traits like auth requirements or side effects. It provides adequate but not detailed transparency.
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?
The description is two sentences, with the first defining the tool's output and the second providing usage guidance. No unnecessary words, perfectly concise.
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?
Given the tool has no output schema, the description adequately lists what it returns (shipments, total weight, shipment count). It is complete for a simple retrieval tool with only one parameter.
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?
Schema description coverage is 100% with a clear description of the manifest_id parameter. The description adds context by mentioning that manifest IDs come from list_manifests, providing marginal additional value beyond the schema.
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 clearly states the tool returns the contents of one manifest including shipments, total weight, and shipment count. It distinguishes from sibling tools like list_manifests by specifying that it is used after that to see details of a specific load.
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?
The description explicitly says to use after list_manifests to see what is on a specific load, providing clear usage context. However, it does not explicitly state when not to use it or list alternatives beyond list_manifests.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail for one shipment: items, extra charges, total amount, and the complete status history. Use after search_shipments when the summary is not enough.
| Name | Required | Description | Default |
|---|---|---|---|
| sp_number | Yes | Shipment number, e.g. SBY-1042 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It describes the return content (items, charges, amount, status history), implying read-only. Adds behavioral context beyond the input schema by detailing the output, though doesn't mention errors or permissions.
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?
Two sentences: first states purpose and output, second gives usage guidance. Front-loads key information with zero wasted words.
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?
Single parameter, no output schema. Description adequately explains what the tool returns and when to use it. Lacks error handling details but is sufficient for the tool's simplicity.
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?
Schema description coverage is 100% for the sole parameter sp_number, which already includes type, pattern, and example. The tool description does not add new parameter semantics; baseline score of 3 is appropriate.
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?
Description clearly states 'Full detail for one shipment' and lists specific data items (items, extra charges, total amount, complete status history). It distinguishes from sibling 'search_shipments' by noting it provides more detail when summary is insufficient.
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?
Provides explicit context: 'Use after search_shipments when the summary is not enough.' This tells the agent when to call this tool vs. the sibling. No exclusions mentioned, but the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List customer invoices with amount, due date, and payment status. Use for billing questions like which customers still have unpaid invoices.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| status | No | Filter by payment status | |
| customer | No | Customer name, substring match |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It mentions returned fields but omits pagination (limit/offset behavior), ordering, or side effects. The tool is likely read-only but not stated. Significant gaps.
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?
Two sentences with no waste. The key action and context are front-loaded. Ideal conciseness.
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?
Given the 4 parameters, no output schema, and no annotations, the description should cover pagination, data ordering, or expected output format. It is adequate for a simple list but lacks completeness for advanced use.
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?
Schema description coverage is 50%; limit and offset have no schema descriptions and are not mentioned in the tool description. Status and customer have schema descriptions but no added context. The description does not explain how to use parameters effectively.
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 clearly states it lists invoices with amount, due date, and payment status, and provides a concrete billing use case. It is distinct from sibling tools which are shipment-related.
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?
The description suggests using it for billing questions but does not explicitly state when not to use or mention alternatives. However, sibling tools cover different domains, so context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List outbound manifests (line-haul loads grouped by destination region and date), with shipment counts and total weight. Use for capacity and dispatch questions.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Manifest date, YYYY-MM-DD | |
| limit | No | ||
| offset | No | ||
| region | No | Destination region city code, e.g. SBY |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes the tool as listing data (implying read-only), but does not explicitly state read-only nature, auth requirements, rate limits, or data freshness. The description is adequate but not comprehensive.
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?
The description is two sentences, front-loading the core functionality and following with usage guidance. No extraneous words; every sentence earns its place.
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?
Given 4 parameters, no output schema, and no annotations, the description adequately covers the tool's purpose and return values (counts, weight). It lacks details on pagination behavior and sorting, but is sufficient for a listing endpoint. Sibling tools are distinct.
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?
Schema description coverage is 50% (date and region have descriptions), and the description mentions date and region as grouping criteria. However, limit and offset lack descriptions both in schema and description, requiring the agent to infer their purpose. The description adds value for date and region but does not compensate for pagination parameters.
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 clearly states it lists outbound manifests grouped by destination region and date, with shipment counts and total weight. The verb 'List' and resource 'outbound manifests' are specific, and the context distinguishes from sibling tools like get_manifest and search_shipments.
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?
The description explicitly says 'Use for capacity and dispatch questions,' providing a clear usage context. It does not detail when not to use or mention alternatives, but the suggested use case is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Price a shipment for a route, weight, and product. Resolves the layered rate table (base per route and weight bracket, product override, destination special) and returns the winning rule with the math, plus the price of the other products for comparison.
| Name | Required | Description | Default |
|---|---|---|---|
| origin | Yes | Origin city code, e.g. SBY | |
| product | Yes | Service product, e.g. STANDARD, EXPRESS, ECONOMY | |
| weight_kg | Yes | Chargeable weight in kilograms | |
| destination | Yes | Destination city code, e.g. JKT |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It transparently describes the logic: 'Resolves the layered rate table (base per route and weight bracket, product override, destination special) and returns the winning rule with the math, plus the price of the other products for comparison.' This gives insight into the calculation process. It does not disclose if the tool is read-only, but the description implies no side effects.
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?
The description is two sentences: the first states the core purpose concisely, and the second adds valuable detail on the internal logic and output. Every sentence is relevant and there is no waste.
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?
The tool has no output schema, so the description must explain return values. It does: 'returns the winning rule with the math, plus the price of the other products for comparison.' This is sufficient for an agent to understand output. It does not cover error conditions or edge cases, but overall it is contextually complete for a pricing tool.
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?
Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining how parameters are used in rate resolution (route, weight brackets, product overrides, destination specials). This provides context that the schema descriptions do not, earning an extra point.
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 clearly states the tool's purpose: 'Price a shipment for a route, weight, and product.' It specifies the inputs (route, weight, product) and what it does (resolves layered rate table, returns winning rule, comparison prices). This distinguishes it from sibling tools like search_shipments or track_shipment.
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?
The description implies usage for pricing a shipment but does not explicitly state when to use this tool versus alternatives or exclude other tools. Sibling tools like get_shipment might also include pricing, but no guidance is provided. Lacks 'when-not-to-use' or explicit alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find shipments by status, creation date range, route, or customer. Returns summaries, newest first. Use this to answer 'where are the late deliveries' or 'what did customer X ship last week' before calling get_shipment for details.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Created on or before, YYYY-MM-DD | |
| from | No | Created on or after, YYYY-MM-DD | |
| limit | No | ||
| offset | No | ||
| origin | No | Origin city code, e.g. SBY | |
| status | No | Filter by current status | |
| customer | No | Customer name, case-insensitive substring | |
| destination | No | Destination city code, e.g. JKT |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions 'Returns summaries, newest first' which adds some behavioral context, but does not explicitly state read-only nature or any destructive potential. Adequate but not thorough.
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?
Two concise sentences. First sentence states purpose and filters, second gives usage guidance and links to sibling. No wasted words.
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?
8 parameters, no output schema. Description covers main use cases and ordering, but lacks details on pagination, return format, or edge cases. Adequate for most scenarios but not fully comprehensive.
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?
Schema coverage is 75%, which is high. Description groups filters logically (route, customer) but doesn't add much beyond schema. Baseline 3 is appropriate.
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?
Clearly states 'Find shipments by status, creation date range, route, or customer'. Distinguishes from sibling get_shipment by mentioning it's for summaries before getting details.
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?
Explicitly says 'Use this to answer...' and provides concrete examples. Tells agent to use get_shipment for details, setting appropriate expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Public tracking timeline for a shipment: the subset of events a recipient would see, without internal ops notes. Use this when the question is 'where is my package'.
| Name | Required | Description | Default |
|---|---|---|---|
| sp_number | Yes | Shipment number, e.g. SBY-1042 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool returns a 'public tracking timeline' and is a subset of events, implying it is read-only and safe. However, it lacks details about potential errors, rate limits, or whether authentication is needed. For a simple tracking tool, this is adequate but not rich.
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?
The description is two sentences (30 words) with no fluff. It front-loads the purpose and usage. Perfectly concise.
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?
For a simple tool with one parameter and no output schema, the description is mostly complete: it explains what it does, when to use it, and what kind of data it returns (public events timeline). However, it does not specify the return structure (e.g., list of events), which could be inferred but is not explicit.
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 one parameter (sp_number) with 100% schema coverage (pattern and description provided). The description does not add additional semantics beyond what the schema already provides. Baseline score of 3 is appropriate.
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 clearly states it provides a 'public tracking timeline' – a subset of events a recipient would see. This distinguishes it from siblings like get_shipment (full shipment details) and search_shipments (search functionality). However, it could be more explicit about differentiation from get_shipment.
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?
Explicitly says 'Use this when the question is "where is my package."' This gives clear guidance on when to use. It does not mention when not to use or alternatives, but the context is clear for its intended purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the status of a shipment. Disabled unless the server runs with ALLOW_WRITES=1; in demo mode the change is kept in memory only. Use only when the user explicitly asks to change a status.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Optional ops note attached to the status event | |
| status | Yes | New status | |
| sp_number | Yes | Shipment number, e.g. SBY-1042 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that the tool is disabled without ALLOW_WRITES=1 and that demo mode changes are in-memory only. Good transparency for a mutation tool.
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?
Two sentences with no waste. Front-loaded with main action. Every sentence adds value.
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?
Covers purpose, usage guidelines, and behavioral constraints adequately. No output schema, but description doesn't explain return values – minor gap for completeness.
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?
Schema description coverage is 100%, so baseline is 3. Description adds no additional meaning beyond the schema; parameters are already well-documented in the schema.
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?
Clearly states 'Set the status of a shipment' – specific verb and resource. Distinguishes from sibling tools like search_shipments, get_shipment (read-only), and track_shipment.
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?
Explicitly states 'Use only when the user explicitly asks to change a status.' Also mentions the ALLOW_WRITES=1 condition and demo mode behavior. Does not name alternative tools but context from siblings is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.1delivery_performanceget_manifestget_shipmentlist_invoiceslist_manifestsquote_shipping_ratesearch_shipmentstrack_shipmentupdate_shipment_statusEach tool serves a distinct purpose: shipment search, detail, tracking, manifest contents, rate quoting, manifest listing, delivery performance, invoices, and status updates. No overlap.
All tools follow a consistent verb_noun pattern with snake_case (e.g., search_shipments, list_manifests, update_shipment_status).
9 tools cover the main logistics operations without being excessive. Each tool serves a clear, non-redundant function.
Covers essential queries (search, detail, tracking, manifests, pricing, performance, invoices) and a status update. Lacks shipment creation or deletion, but these are outside the stated read-heavy scope.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Multi-carrier shipping for AI agents: compare rates, buy labels, track packages, validate addresses
Neutral freight reference + validation layer for AI agents: ADR, HS, UN/LOCODE, freight math
RixFreight logistics quotes and route info via AI agents
India shipping for AI agents: Shiprocket courier serviceability, create orders, track AWB.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Azzaraell/logistics-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
