warp-agent-mcp is an MCP server that lets AI agents quote, book, track, and manage real freight shipments on the Warp network across multiple shipping modes.
Quote Shipments
Cargo van (1–3 pallets), box truck (1–12 pallets), full truckload (53' dry van), LTL (with optional dims/commodity for firm pricing), and multi-stop FTL routes
Book Shipments
Book any quoted shipment using a quote ID, with pickup/delivery addresses, time windows, and accessorial services
Track Shipments
Track by shipment ID or tracking number, and view full event timelines
Documents & Invoices
Retrieve invoices (line items, payment status) and shipment documents (BOL, POD, customs forms)
Account & History
Log in, check payment method status, view recent bookings, quote history, and lane history
Saved Resources
List saved pickup/delivery locations; create, list, and delete reusable load templates (named shipment configs)
Analytics & System
View booking/revenue analytics by source, and check API health/key validity
Provides tools to quote, book, and track LTL, FTL, cargo van, box-truck, and multi-stop shipments via the Warp freight API.
warp-agent-mcp is the first MCP server for booking real freight. It's a Model
Context Protocol server for the Warp freight network that
lets an AI agent quote, book, and track LTL, FTL, cargo van, box-truck, and
multi-stop shipments — straight from Claude Desktop, Claude Code, Cursor, Windsurf,
Continue, or any MCP-compatible client — on the same production network the
wearewarp.com customer portal runs on. Open source, MIT, one npx line to install.
If you're comparing freight MCP servers, this is the one that completes the transaction, not just the lookup:
It books real freight, not just quotes or tracking. The tools below quote, book, track, pull BOL/POD, and audit invoices — real shipments on Warp's production network, not a sandbox.
Multi-mode, not parcel. LTL, FTL, box truck, and cargo van. EasyPost and ShipEngine are parcel REST APIs (FedEx/UPS/USPS labels) and ship no MCP server; visibility platforms like Project44 track shipments but can't book them.
First to ship. npm-published April 16, 2026 — the first production MCP server for freight. Open source under MIT.
Works in every MCP client today. Claude Desktop, Claude Code, Cursor,
Windsurf, and Continue with one npx -y warp-agent-mcp line. ChatGPT works the
day OpenAI ships native MCP — same server, no changes.
Verifiable. The machine-readable discovery manifest at https://www.wearewarp.com/.well-known/mcp.json lists every tool, a live no-auth health endpoint runs at https://www.wearewarp.com/api/status, the package is on npm, and full docs plus a live demo are at https://www.wearewarp.com/agents/mcp.
Related MCP server: ShippingRates
31 tools that let an AI agent talk to your Warp account:
Tool | What it does |
| Start here. Compare every eligible mode (van/box truck/LTL/FTL) in one parallel call and get a decision-complete recommendation with the trade-off math |
| Quote a 1–3 pallet cargo van shipment |
| Quote a 1–12 pallet box truck shipment |
| Quote a full truckload (53' dry van) |
| Quote LTL — Warp's flagship freight product |
| Multi-carrier LTL comparison - 30+ carriers ranked by price |
| Quote many lanes in one call (a whole spreadsheet / CSV) |
| Book any quote by id, with pickup + delivery addresses |
| Book many already-quoted lanes in one call |
| Quote a multi-stop FTL route — one truck, 3+ stops in order |
| Book a quoted multi-stop route as per-leg shipments |
| Track a shipment by id or order id |
| Full tracking event timeline for a shipment |
| Past shipments on your lanes |
| List recent bookings |
| List recent quotes across all sessions |
| List your saved pickup/delivery locations |
| List your saved reusable load configurations |
| Save a reusable load configuration (weight + dims + class) |
| Delete a saved load template by id |
| Invoice for a delivered shipment |
| Shipment documents (BOL, POD, customs) |
| Log in from inside the MCP, no portal visit needed |
| Check whether a card is on file |
| API health + key validity check |
| Bookings + revenue rollup by source |
Removed in 0.5.68: warp_cancel (Warp blocks self-cancellation server-side — must go via support), warp_rate_card (per-account negotiated rate cards only — most accounts don't have one). multistop_quote + multistop_book were also removed in 0.5.68 and re-added in 0.14.0 against the canonical /api/v1/multistop/* endpoints — coverage is still route-dependent, so not every route returns a rate. Contact support@wearewarp.com if you need either of the removed tools.
Paste this URL into your AI client's custom connector settings and sign in with Warp:
https://mcp.wearewarp.com/api/mcpNo install, no API key, no config file. Sign in once (OAuth) and the full toolset appears. Works in Claude.ai, Claude Desktop, and Claude Code. This is the primary way to use Warp.
For clients without a custom-connector UI (Cursor, Windsurf, Continue), or if
you'd rather hold a local wak_live_* key:
npm install -g @warpfreight/cli-agent
warp-agent signupThat command creates a Warp account, issues you a wak_live_* token, saves it
to ~/.warp/config.json, and auto-wires this MCP into Claude Desktop, Cursor,
and Claude Code. Restart your AI client to load the new tools.
Add a payment method at https://www.wearewarp.com/agents/account.
If you'd rather wire this up by hand, add to Claude Desktop config:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"warp": {
"command": "bash",
"args": ["-lc", "npx -y warp-agent-mcp"]
}
}
}The MCP reads the API key from ~/.warp/config.json on every tool invocation,
so warp-agent login / warp-agent signup take effect without restarting your
AI client.
For Cursor or Claude Code, the same npx -y warp-agent-mcp command works in
their respective MCP config files.
After install + signup + restart, ask your AI agent:
Quote LTL from 90007 to 90038, pickup June 25, 2 pallets at 500 lb.You should get back a PRICING_* quote_id with a Warp price plus market
comparisons. Add Book that quote, pickup at 1234 S Hoover St LA 90007, deliver to 6464 Sunset Blvd LA 90038. and the agent will buy the label and return a
tracking number.
Env var | Purpose |
| API key fallback if |
| Override the API base URL. Defaults to |
Node.js 20 or later (the MCP SDK requires native fetch and Web Standard APIs)
Sandbox is not yet supported in the MCP. The freight proxy (/warp/freights/*)
currently requires a live wak_live_* key; sandbox keys return 401 on quote
and booking endpoints. Sandbox support is planned for a future release.
@warpfreight/cli-agent
— the auto-provisioning CLI that installs this MCP into every detected AI
client. Same backend, command-line surface for scripting + CI.
Issues and PRs welcome at https://github.com/warpfreight/warp-agent-mcp.
Data collected and sent to Warp servers (wearewarp.com):
ZIP codes and shipping addresses (quote and book operations)
Contact names, phone numbers, and email addresses (booking only)
Your Warp account email and API key (stored locally in ~/.warp/config.json — never transmitted beyond the Warp API)
Data NOT collected:
No analytics or telemetry is sent to any third party
Payment card details are never handled by this package — charges are processed server-side by Stripe via the Warp backend
Storage: Credentials are stored locally in ~/.warp/config.json on your machine. No data is stored by the MCP server itself between calls.
Third parties: Shipment data is shared with the selected freight carrier (Warp or market carriers) as required to book and execute the shipment.
Retention: Data retention is governed by Warp's Privacy Policy.
Contact: privacy@wearewarp.com
MIT © Warp Technology, Inc.
Show bookings analytics: total revenue, shipment count, breakdown by source (mcp vs cli). Use this to track how much revenue has been generated through AI tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, confirming read-only nature. Description adds value by detailing what metrics are returned (revenue, shipments, breakdown). No contradictions; no additional behavioral traits needed.
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, front-loaded with main purpose. No redundant information; every sentence is valuable.
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?
Despite no output schema, description fully explains return values (total revenue, shipment count, breakdown). Given zero parameters and clear sibling differentiation, the description is complete and 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?
Input schema has zero parameters (100% coverage), so description correctly adds no parameter info. Baseline 4 for no params; description compensates by explaining the output content.
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 specifies the verb 'Show' and resource 'bookings analytics' with explicit outputs: total revenue, shipment count, breakdown by source. Distinguishes from sibling tools like warp_book, warp_quote_history, etc., which are operational, not analytical.
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 use case: 'track how much revenue has been generated through AI tools.' No explicit when-not-to-use, but the context of sibling tools makes it clear this is for analytics, not actions like booking or tracking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Book a quoted shipment using any quote_id or option id returned from a quote tool (Warp or market carrier). Requires quote_id + pickup and delivery addresses. Auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| quote_id | Yes | Quote ID from warp_quote_id (Warp) or id field of any market option returned by a quote tool. Use the id from your MOST RECENT quote — market-option ids rotate on every quote call and stale ids are rejected. | |
| pickup | No | Pickup address. Required if no default shipper is saved on your account. | |
| delivery | No | Delivery address. Required if this lane has not been shipped before. | |
| notes | No | Special instructions for the shipment | |
| reference | No | Your internal reference number | |
| accessorials | No | Pickup/delivery accessorial services. Should match the accessorials used when quoting. | |
| pickup_window | No | Pickup time window, 24h HH:MM, e.g. { from: '08:00', to: '17:00' }. Defaults to a full business day if omitted. | |
| delivery_window | No | Delivery time window, 24h HH:MM, e.g. { from: '09:00', to: '12:00' }. Defaults to a full business day if omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description adds no further behavioral context. It mentions auth requirement but does not detail side effects like irreversible booking or confirmation behavior. The description adds minimal value over annotations.
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 a single sentence with no wasted words and front-loads the key action. It could be slightly more structured but remains effective.
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?
Despite 8 parameters and no output schema, the description gives a brief overview. It lacks information on return values, error handling, or confirmation behavior, which would help the agent fully understand the tool's effects.
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 all parameters are documented in the schema. The description provides a high-level summary ('Requires quote_id + pickup and delivery addresses') without duplicating details, which 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 the action (book a shipment) and the resource (quoted shipment using quote_id). It distinguishes from sibling quote tools by specifying it uses a quote_id or option id from a quote tool.
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 indicates when to use (after obtaining a quote) and notes prerequisites (quote_id, addresses, auth). It stops short of explicitly stating when not to use or naming alternatives, but sibling context and the phrase 'using any quote_id or option id' provide implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quote a 26' box truck shipment (1-12 pallets, firm price, 15-min expiry)
| Name | Required | Description | Default |
|---|---|---|---|
| origin_zip | Yes | 5-digit US ZIP code | |
| destination_zip | Yes | 5-digit US ZIP code | |
| pallets | Yes | Number of pallets (1-12) | |
| weight_lbs_per_pallet | Yes | Weight per pallet in lbs | |
| pickup_date | Yes | Pickup date YYYY-MM-DD | |
| commodity | No | Commodity description | |
| pickup_services | No | Pickup accessorials: pickup-appointment, liftgate-pickup, residential-pickup, limited-access-pickup, inside-pickup, driver-assist-pickup | |
| delivery_services | No | Delivery accessorials: delivery-appointment, liftgate-delivery, residential-delivery, limited-access-delivery, inside-delivery, driver-assist-delivery |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations (readOnlyHint=true) by noting 'firm price' and '15-min expiry'. This helps the agent understand the pricing behavior and time sensitivity. No contradiction with annotations.
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 a single, dense sentence containing key constraints and behaviors. It is front-loaded and contains no unnecessary 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?
Given the tool's complexity (8 parameters, no output schema), the description covers high-level behavior (pricing, expiry) but lacks details about the response structure. However, the 100% schema coverage compensates, making the description adequate for an agent to understand the tool's role.
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 the description does not need to add per-parameter details. The description provides overall context (26' truck, firm price) that aids understanding but does not add significant meaning beyond the schema. 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 the tool's function: 'Quote a 26' box truck shipment' with specific constraints (1-12 pallets, firm price, 15-min expiry). This distinguishes it from sibling tools like warp_ftl_quote, warp_ltl_quote, and warp_van_quote by specifying the truck type and capacity.
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 box truck quotes but does not explicitly state when to use this tool versus alternatives. However, the context from sibling tool names and the clear purpose allow an agent to infer appropriate usage. No exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a saved load template by its id (starts with lt_). Auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| load_template_id | Yes | Template id to delete (starts with lt_) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide destructiveHint=true. The description adds the requirement for authentication, which is not in the annotations. It does not mention reversibility or side effects, but for a simple delete, this is adequate.
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 a single sentence with no unnecessary words. It is extremely concise and to the point.
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 one-parameter delete tool, the description covers purpose, parameter format, and auth requirement. No output schema is needed, and it is complete for its complexity.
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?
The schema covers the parameter fully, but the description adds that the id starts with 'lt_', providing extra context 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 action (delete), the target (saved load template), and the identifier format (starts with lt_). It distinguishes from sibling tools like warp_save_load_template and warp_load_templates.
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 mentions 'Auth required,' which is a condition for usage. While not explicitly stating alternatives, the context and sibling list make it clear when to use this tool vs others, but it could be more explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full tracking event history for a shipment (timeline of pickups, in-transit updates, deliveries). Auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| shipment_id | Yes | Shipment ID from warp_book response |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, and the description adds 'Auth required' and full event history scope. No contradictions, but the description does not detail output format or limits, relying on schema. With annotations, bar is lower; this adds moderate value.
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?
Description is a single sentence with front-loaded action and parenthetical examples. It is concise and readable, though could be slightly more structured (e.g., bullet points for event types).
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?
No output schema exists, so description should hint at return structure. It mentions event types (pickups, in-transit, deliveries) but not array structure or pagination. Adequate but not fully complete.
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?
The schema has one parameter (shipment_id) with clear description. Schema coverage is 100%, so description adds no extra 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?
The description clearly states the verb 'Get' and the resource 'full tracking event history for a shipment', with examples (timeline of pickups, in-transit updates, deliveries). It distinguishes from sibling tools like warp_track (likely simpler status) and warp_status (current 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?
The description implies usage when needing a full event history but does not explicitly state when to use this tool versus alternatives like warp_track. It mentions 'Auth required' but lacks direct comparison or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quote a full truckload (53' dry van). Only origin, destination, and date required.
| Name | Required | Description | Default |
|---|---|---|---|
| origin_zip | Yes | 5-digit US ZIP code | |
| destination_zip | Yes | 5-digit US ZIP code | |
| pickup_date | Yes | Pickup date YYYY-MM-DD | |
| pallets | No | Pallets (optional, display only) | |
| weight_lbs_per_pallet | No | Weight per pallet (optional) | |
| commodity | No | Commodity description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, marking this as a safe read operation. The description adds that it's a quote but does not disclose further behaviors like return format or whether it saves data. With annotations covering safety, a 3 is appropriate.
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 a single, front-loaded sentence with no waste. It could be slightly more structured (e.g., listing parameters), but remains efficient.
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 6 parameters, no output schema, and no details on return values or behavior, the description is minimal. It covers the core but lacks context on what the quote looks like or how it's used in the workflow.
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 all parameters are documented. The description adds context by highlighting required parameters and noting optional ones, going beyond the schema's descriptions.
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 verb 'Quote' and resource 'full truckload (53' dry van)', and specifies required inputs. It distinguishes from siblings like warp_ltl_quote and warp_box_truck_quote.
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?
It explicitly says 'Only origin, destination, and date required', establishing minimum requirements. However, it does not provide when-to-use vs alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List shipment documents (BOL, POD, customs forms, etc.). Returns download URLs. Auth required. To fetch the Bill of Lading, pass document_type='bol' — this is how EXTERNAL / brokered (market-carrier) BOLs are returned now, not just Warp-carrier ones.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | Order ID (typically the same as shipment_id) | |
| document_type | No | Filter to one document type. Common: 'bol' (Bill of Lading — required for external/market carrier BOLs), 'pod' (proof of delivery). Omit to list all documents. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds that auth is required and that BOLs are returned for external carriers, which annotations (readOnlyHint=true) do not cover. No contradictions; the read-only nature is consistent. Additional context beyond annotations.
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, no unnecessary words. First sentence states core purpose, second provides critical usage nuance. Efficient and well-structured.
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 read-only list tool with two parameters and no output schema, the description is reasonably complete: it covers what documents are listed, that URLs are returned, and gives special note about BOLs. Could mention that it's a filtered list, but overall adequate.
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?
Both parameters have schema descriptions, but the description adds practical insight: order_id is typically same as shipment_id, and document_type='bol' is required for external BOLs. This goes beyond the schema's basic descriptions.
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 the action 'List shipment documents', specifies examples (BOL, POD, customs forms), and mentions return type (download URLs). Distinct from sibling tools like warp_track or warp_book.
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 guidance on using document_type='bol' for external BOLs, and explains that omitting document_type lists all documents. Could be improved by mentioning when not to use this tool or alternatives, but current guidance is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the invoice for a delivered shipment (line items, taxes, payment status). Auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | Order ID (typically the same as shipment_id) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description adds 'Auth required' and the precondition of a delivered shipment. However, it does not disclose error behavior, rate limits, or response format beyond what annotations provide.
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?
Single sentence of 15 words, front-loaded with the purpose and key constraints. No redundant information.
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 required parameter and good annotations, the description covers purpose, precondition (delivered shipment), and auth requirement. Lacks explicit return format, but this is acceptable given no output schema.
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% and already describes the order_id parameter sufficiently. Description adds 'Auth required' but no further parameter-specific details, so value beyond schema is minimal.
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 the tool retrieves an invoice for a delivered shipment, specifying the verb 'retrieve' and resource 'invoice for a delivered shipment'. It distinguishes from siblings like warp_payment_status and warp_get_documents by focusing on invoice retrieval.
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 use only for delivered shipments but does not explicitly state when not to use or mention alternatives. No guidance is provided on prerequisites or error scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get shipping history for your lanes (past shipments, last consignee, counts). Auth required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description reinforces it as a read operation. It adds the behavioral detail that authentication is required, which is not in annotations.
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 extremely concise with two short sentences that convey the core purpose and an important requirement, with no unnecessary 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?
For a simple read-only tool with no parameters and no output schema, the description provides a reasonable overview of what to expect (history, last consignee, counts) and the auth requirement. It could be slightly more specific about the time range or data scope, but overall adequate.
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?
The tool has no parameters, so the description adds no parameter-specific details. However, it explains what the tool returns, which is sufficient given zero parameters. Baseline for 0 params is 4.
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 retrieves shipping history for lanes, including specific data like past shipments, last consignee, and counts. This distinguishes it from sibling tools like warp_quote_history or warp_events.
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 mentions 'Auth required' as a prerequisite but provides no guidance on when to use this tool versus alternatives, nor any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent bookings for this API key, newest first. Auth required. Renders an interactive shipments card (click a shipment to expand pickup/delivery, freight, and a tracking link).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max bookings to return (default 25, max 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds that auth is required and that it renders an interactive card with expandable details. This adds value beyond annotations without contradiction.
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 states purpose and ordering, second adds behavioral details. No fluff, front-loaded with key info.
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 list tool with one optional param and no output schema, the description covers purpose, auth, ordering, and UI behavior. It hints at output data via expandable fields, but lacks explicit return structure. Still fairly complete.
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% and the description provides no additional parameter info beyond the 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?
The description clearly states it lists recent bookings for the current API key with newest first ordering. It distinguishes from sibling tools like warp_book (create) and warp_track (tracking).
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 indicates authentication is required and provides the ordering, but does not explicitly state when to use or not use this tool versus alternatives. The context is clear enough for an agent to select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the agent's saved load templates — reusable shipment configs (name, dims, weight, commodity). Recall one to quote/book a repeat kind of load without re-entering details. Auth required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. The description adds 'Auth required' and details the content of templates (name, dims, weight, commodity). This is useful context beyond annotations, though it does not cover potential edge cases like renaming or pagination.
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 convey the purpose and use case without redundancy. Every word adds value, and the structure is front-loaded with the main action.
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 list operation with no parameters and no output schema, the description fully covers what the tool does, why it exists, and prerequisites. No gaps are apparent given the tool's complexity.
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?
With zero parameters, the schema coverage is 100% and the description clarifies that no filtering is needed: it lists all templates. This adds meaning by setting expectations for the scope of the operation.
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 verb 'List' and the resource 'agent's saved load templates'. It distinguishes itself from sibling tools like warp_save_load_template and warp_delete_load_template by specifying that it lists reusable shipment configs, implying it is a read-only retrieval operation.
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 provides clear context on when to use the tool: 'Recall one to quote/book a repeat kind of load without re-entering details.' It also notes 'Auth required.' Without explicit exclusions or alternatives, the guidance is strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the agent's saved pickup/delivery locations (addresses Warp has on file for this account), so you can reuse them when booking instead of re-typing addresses. Auth required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint: true. The description adds context about returning saved locations and requiring authentication. It does not contradict annotations and is adequate for a simple read-only list 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, zero waste. The first sentence states the action concisely, and the second adds the reuse purpose. Perfectly front-loaded and efficient.
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 zero-parameter tool with no output schema, the description fully covers what the tool does, why to use it, and what data it retrieves. No gaps given the 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?
No parameters are defined, so the schema coverage is 100%. The description does not need to add parameter-specific details, and the baseline score of 4 applies.
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 'List the agent's saved pickup/delivery locations', specifying the verb 'list' and the resource 'saved pickup/delivery locations'. It distinguishes from siblings like warp_book or warp_list_bookings by focusing on saved address reuse.
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 explains the purpose ('so you can reuse them when booking instead of re-typing addresses') and notes 'Auth required'. It implicitly advises use when needing saved addresses but lacks explicit exclusion of when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log in to Warp with email and password. Saves credentials locally so booking tools work. Call this if the user needs to authenticate or if warp_payment_status says no key is configured.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Warp account email | ||
| password | Yes | Warp account password |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effect of saving credentials locally, beyond the title. Could mention security considerations but adequate for a simple auth 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, no fluff, front-loaded with key information. Efficient.
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 condition, and key side effect. No output schema needed for a simple action. Missing possible error handling but not critical.
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 provides full descriptions for both parameters (email format, password minLength). Description adds no extra meaning beyond schema, meeting baseline for 100% schema coverage.
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 the action (log in), resource (Warp), and purpose (enables booking tools). It distinguishes from other warp tools.
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 when to call: when user needs authentication or when warp_payment_status indicates no key configured. Provides clear context and references a sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quote an LTL shipment. Provide dims + commodity for a firm quote; omit for indicative pricing (FAK rates if no freight class). Do not editorialize the results. Do not declare a winner or recommend a specific carrier. Present Warp's quote first, then list market options as context. Let the user decide.
| Name | Required | Description | Default |
|---|---|---|---|
| origin_zip | Yes | 5-digit US ZIP code | |
| destination_zip | Yes | 5-digit US ZIP code | |
| pickup_date | Yes | Pickup date YYYY-MM-DD | |
| pallets | No | Number of pallets | |
| weight_lbs_per_pallet | No | Weight per pallet in lbs | |
| commodity | No | Commodity description | |
| length_in | No | Pallet length in inches | |
| width_in | No | Pallet width in inches | |
| height_in | No | Pallet height in inches | |
| freight_class | No | Freight class (optional, FAK rates used if omitted) | |
| stackable | No | Whether pallets are stackable | |
| hazmat | No | Hazardous materials flag | |
| pickup_services | No | Pickup accessorials: pickup-appointment, liftgate-pickup, residential-pickup, limited-access-pickup, inside-pickup, driver-assist-pickup | |
| delivery_services | No | Delivery accessorials: delivery-appointment, liftgate-delivery, residential-delivery, limited-access-delivery, inside-delivery, driver-assist-delivery |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description complements the readOnlyHint annotation by adding behavioral constraints such as not editorializing results, not recommending carriers, and presenting Warp's quote first. There is no contradiction; it adds important context beyond what annotations provide.
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 concise with four sentences, each serving a purpose. It front-loads the primary function and includes necessary behavioral instructions without superfluous text.
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?
While the description covers input usage and behavioral guidelines well, it lacks explicit details about the output format or structure. The phrase 'Present Warp's quote first, then list market options as context' provides some output context, but the absence of an output schema makes it slightly less complete for an agent to precisely understand the response.
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?
The input schema has 100% coverage, but the description adds value by explaining that providing dims+commodity yields a firm quote, while omitting them yields indicative pricing with FAK rates. This semantic guidance is not present in the schema descriptions.
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 'Quote an LTL shipment' and distinguishes between firm and indicative quotes based on providing dims and commodity. It uniquely identifies this as an LTL-specific tool, differentiating from siblings like warp_ftl_quote and warp_box_truck_quote.
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 provides explicit guidance: when to provide dims+commodity for firm quotes vs omit for indicative pricing, and how to present results (do not editorialize, present Warp's quote first, then market options). It also tells the agent not to recommend a carrier, ensuring proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if the current Warp account has a payment method on file. Call this if the user asks about their payment status, or before booking if you want to confirm they can book. Returns has_card and onboard_url if a card needs to be added.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description adds return value details (has_card and onboard_url). No destructive behavior is implied, and the description is consistent with annotations. A small improvement would be mentioning if there are any side effects, but for a simple read check this is sufficient.
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 three sentences, front-loading the purpose and then usage/return. It is clear and concise, though slightly redundant in stating 'returns' after the call scenarios. Still efficient.
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 zero-parameter, no-output-schema tool, the description covers purpose, usage conditions, and return values completely. It is self-contained and requires no additional context.
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 are no parameters, so schema coverage is trivially 100%. The description does not need to add parameter info, and baseline for 0 params is 4.
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 verb 'check' and resource 'payment method on file', which distinguishes this from sibling tools like warp_status or warp_get_invoice. It is specific and unambiguous.
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 when to call this tool: 'if the user asks about their payment status, or before booking if you want to confirm they can book.' This provides excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your recent freight quotes (LTL, van, box truck, FTL) from all sessions. Useful for surfacing prior pricing on similar lanes. Auth required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds 'auth required' beyond readOnlyHint annotation, but could detail more about session behavior or authentication failures.
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 front-loaded sentences with no extraneous information.
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?
Sufficient for a parameterless tool, though missing details on sorting, filtering, or response format.
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?
No parameters; description provides context of 'from all sessions', meeting baseline for schema coverage.
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 action (list) and resource (recent freight quotes), specifying types and distinguishing from sibling tools for specific quotes.
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 use case ('surfacing prior pricing'), but lacks explicit when-not-to-use or alternative tools, though context implies read-only history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a reusable load template (a named shipment config) so it can be recalled for repeat lanes. Auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Friendly name, e.g. 'Standard 2-pallet LA load' | |
| weight_lbs | Yes | Total weight in lbs | |
| length_in | Yes | Length in inches | |
| width_in | Yes | Width in inches | |
| height_in | Yes | Height in inches | |
| commodity | No | Commodity description | |
| freight_class | No | Freight class (optional; FAK pricing if omitted) | |
| stackable | No | Whether the freight is stackable | |
| hazmat | No | Whether the freight is hazmat |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations beyond title, description only notes 'Auth required'. Does not disclose whether duplicate names are handled, error behavior, or side effects. Adds minimal behavioral context.
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?
Single sentence, front-loaded with action and purpose. 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?
With 9 parameters and no output schema, the description is sparse. Does not explain return values or error handling. However, high schema coverage partially compensates.
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. Description does not add any additional meaning beyond the schema for each parameter.
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 'Save a reusable load template', a specific verb and resource. Siblings include delete and list templates, so purpose is well-distinguished.
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?
States 'so it can be recalled for repeat lanes', providing a use case. Does not explicitly mention when not to use or alternatives, but context of siblings makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check Warp API health and version. Also validates your API key if one is configured.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint annotation by specifying that it also validates the API key if configured. No contradictions with annotations.
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 with no wasted words. Front-loaded with the primary purpose.
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 zero-parameter health check without output schema, the description covers the basic functionality. However, it could mention the expected response format (e.g., health status, version string) for full 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?
No parameters exist, so the description correctly avoids parameter details. Schema coverage is 100% (vacuously), and the baseline of 4 is appropriate as there is no missing parameter information.
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 checks API health and version, and validates the API key if configured. This is specific and distinguishes it from sibling tools which are more operation-specific.
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 verifying API connectivity and key validity, but does not explicitly mention when to use this tool versus alternatives or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Track a shipment by ID or tracking number. Auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| shipment_id | Yes | Shipment ID or tracking number (e.g. S-12345-2616) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds that auth is required, which is useful but does not disclose other behaviors like return format or side effects. No contradiction.
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 perfectly concise: two short sentences, no filler, front-loaded with the core action.
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 no output schema, the description could have noted what response the tool returns (e.g., status, delivery date). It is adequate for a simple tool but lacks details about the return value.
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?
With 100% schema coverage, the schema already describes the parameter fully. The description repeats 'by ID or tracking number' without adding new meaning, so 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 the action (track) and resource (shipment), and specifies the method (by ID or tracking number). It effectively distinguishes from sibling tools like warp_book or warp_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?
The description mentions 'Auth required' but gives no explicit guidance on when to use this tool versus alternatives such as warp_status or warp_events. The usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quote a cargo van shipment (1-3 pallets, firm price, 15-min expiry)
| Name | Required | Description | Default |
|---|---|---|---|
| origin_zip | Yes | 5-digit US ZIP code | |
| destination_zip | Yes | 5-digit US ZIP code | |
| pallets | Yes | Number of pallets (1-3) | |
| weight_lbs_per_pallet | Yes | Weight per pallet in lbs | |
| pickup_date | Yes | Pickup date YYYY-MM-DD | |
| commodity | No | Commodity description | |
| pickup_services | No | Pickup accessorials: pickup-appointment, liftgate-pickup, residential-pickup, limited-access-pickup, inside-pickup, driver-assist-pickup | |
| delivery_services | No | Delivery accessorials: delivery-appointment, liftgate-delivery, residential-delivery, limited-access-delivery, inside-delivery, driver-assist-delivery |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the readOnlyHint annotation: 'firm price, 15-min expiry' indicates the quote's binding nature and limited validity. This informs the agent that the quote is not just a snapshot but a guaranteed offer that expires. No contradiction with annotations.
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 a single sentence that conveys the core purpose and key constraints efficiently. Every word is meaningful, with no redundancy or fluff.
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 8 parameters (5 required) and no output schema, the description would benefit from clarifying what the tool returns (e.g., price, reference number, expiry timestamp). While the description hints at output ('firm price, 15-min expiry'), it lacks explicit details about the response structure, which is needed for a quoting 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?
All 8 parameters have descriptions in the input schema (100% coverage), so the description adds minimal new information about parameters. The description's mention of '1-3 pallets' aligns with the pallets parameter range, but does not elaborate beyond schema details. 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?
The description explicitly states the tool's purpose: 'Quote a cargo van shipment (1-3 pallets, firm price, 15-min expiry)'. This clearly identifies the resource (cargo van shipment), the action (quote), and key constraints (pallet range, price type, expiry). It distinguishes from sibling tools like warp_box_truck_quote or warp_ltl_quote by specifying cargo van and pallet limits.
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 cargo van shipments with 1-3 pallets, providing clear context for when to use this tool. However, it does not explicitly state when not to use it or mention alternative tools for different shipment sizes. The sibling tools (box truck, FTL, LTL) are related but not referenced.
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.
v0.10.1warp_analyticswarp_bookwarp_box_truck_quotewarp_delete_load_templatewarp_eventswarp_ftl_quotewarp_get_documentswarp_get_invoicewarp_lane_historywarp_list_bookingswarp_load_templateswarp_locationswarp_loginwarp_ltl_quotewarp_payment_statuswarp_quote_historywarp_save_load_templatewarp_statuswarp_trackwarp_van_quoteScored across 20 tools
Each tool has a distinct purpose without overlap: quotes are separated by vehicle type, CRUD for load templates is split, tracking and analytics are separate, etc.
All tools start with 'warp_' and are descriptive snake_case, but there is a mix of verb-first (e.g., warp_book) and noun-first (e.g., warp_analytics) patterns, causing slight inconsistency.
20 tools cover the full shipping lifecycle without being overwhelming; each tool has a clear role and the count is well-scoped for the domain.
Core workflow (quote, book, track, documents, invoice) is covered, plus history and analytics; minor gaps include missing update/cancel for shipments and update for load templates.
AI-native platform: cybernetic freight agents transact, verify, find services. Get verified leads.
RixFreight logistics quotes and route info via AI agents
Multi-carrier shipping functionality with built-in, discounted carrier accounts. Compare rates, generate PDF shipping labels, schedule pickups and track packages in automated way or in your chatbox, no coding required. This is a demo server that is functional with no account needed and no auth. For production use please find our production version.
Multi-carrier shipping for AI agents: compare rates, buy labels, track packages, validate addresses
