Multi-carrier shipping for AI agents: compare rates, buy labels, track packages, validate addresses
Scored across 4 tools
Each tool has a clearly distinct role: list provides discovery, describe gives parameter details, and read/write execute perform actions. There is no overlap between them, and the read/write split eliminates ambiguity about which tool to use.
All tool names follow the 'shippo_' prefix with snake_case, using descriptive verbs: list, describe, read_execute, write_execute. The naming pattern is uniform and predictable, clearly indicating function and side-effect type.
With only 4 tools, the server effectively wraps 74 API operations via a meta-interface. This is a well-scoped design that avoids overwhelming the agent while providing full access. The tool count is appropriate for the server's purpose of exposing a large API compactly.
The combination of list, describe, and read/write execute tools covers the entire Shippo API surface, including all 17 categories and 74 operations. There are no missing lifecycle operations because any read or write operation can be invoked through the corresponding execute tool, making the surface complete.
Get the full input schema, detailed description, and kind classification for a Shippo operation. Call this AFTER shippo_list_tools to learn the exact parameters (required + optional, types, enum values) AND to confirm which execute tool to use (read or write).
Pass the short operation name from shippo_list_tools (e.g. 'listWebhooks', 'CreateAddress', 'GetTrack'). Name lookup is case-insensitive.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Operation short name from shippo_list_tools. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | Which execute tool accepts this operation. |
| name | Yes | Operation short name (canonical casing). |
| category | Yes | User-facing category (e.g. 'Webhooks'). |
| description | Yes | Full operation description. |
| inputSchema | Yes | JSON Schema for the operation's `arguments` object. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true) are consistent with description. Description adds that name lookup is case-insensitive, and that it returns kind classification to guide execute tool selection.
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 well-structured paragraphs, front-loaded with purpose, then usage context. No wasted words. Every sentence provides essential guidance.
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 role (describe a Shippo operation) and presence of output schema, the description fully covers what the agent needs: what it returns, when to call it, and how it relates to sibling tools.
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?
Only one parameter 'name' with schema description. Description adds value by noting case-insensitivity and that it's the short name from list tools, beyond the schema itself. Schema coverage 100% gives baseline 3, so 4 is justified.
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 it gets 'full input schema, detailed description, and kind classification' for a Shippo operation. Distinguishes from siblings by specifying use after shippo_list_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 says 'Call this AFTER shippo_list_tools' and 'to confirm which execute tool to use (read or write).' Provides alternatives (list, execute) and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Shippo API operations available through this server. Use this FIRST to discover what operations exist before calling shippo_describe_tool or one of the execute tools.
Returns each operation's short name, category, kind (read or write), and one-line description. Filter by category (e.g. 'Webhooks', 'Manifests', 'Address Book'), kind ('read' or 'write'), or query (natural-language keywords matched against names and descriptions). Pass no arguments to list everything.
There are ~74 operations spanning 17 categories: Addresses, Address Book, Batches, Carrier Accounts, Customs, Manifests, Orders, Parcels, Pickups, Rates, Refunds, Service Groups, Shipments, Shippo Accounts, Tracking, Transactions, Webhooks.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional kind filter. | |
| query | No | Optional natural-language search keywords. | |
| category | No | Optional category filter (case-insensitive substring). |
| Name | Required | Description |
|---|---|---|
| count | Yes | Number of operations matched after filtering. |
| tools | Yes | Matched operations, sorted case-insensitively by name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds details beyond annotations: returns short name, category, kind, description; mentions ~74 operations and 17 categories. No contradictions.
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?
Front-loaded with purpose and usage, well-structured sentences without redundancy. 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, filtering, output content, and scope. Output schema exists, so return format details are appropriately omitted.
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 three parameters are described in schema; description adds context like case-insensitive category, natural-language query, and kind filter options.
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 it lists Shippo API operations for discovery, with a clear verb and resource. It distinguishes from siblings by specifying it should be used first.
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?
Clear guidance to use this tool first before others, with optional filtering. Lacks explicit 'when not to use' but context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a READ-only Shippo API operation (List*, Get*, Validate*, Parse*, etc.). Returns the Shippo API response. Does NOT mutate any state.
Use this tool ONLY for operations whose kind is 'read' per shippo_describe_tool. Calling a write operation here will be rejected — use shippo_write_execute_tool for those.
Get the operation name from shippo_list_tools and its argument shape from shippo_describe_tool first. Name lookup is case-insensitive.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Read-operation short name. | |
| arguments | Yes | Operation arguments per its inputSchema. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by explicitly stating 'Does NOT mutate any state' and 'Returns the Shippo API response', providing additional behavioral context beyond the 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 concise, with only a few sentences that front-load the purpose and follow with clear usage instructions. Every sentence adds value; 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 presence of an output schema and annotations, the description covers all necessary aspects: what the tool does, how to use it correctly, prerequisites, and error conditions (rejection). It is fully complete for an effective tool definition.
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 the baseline is 3. The description adds no additional parameter semantics beyond repeating the schema's description: 'Read-operation short name' and 'Operation arguments per its inputSchema.' This does not improve upon 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 it executes a READ-only Shippo API operation (List*, Get*, Validate*, Parse*, etc.) and returns the Shippo API response, explicitly noting it does not mutate state. This distinguishes it from the sibling tool shippo_write_execute_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 provides explicit guidance: use only for 'read' operations per shippo_describe_tool, warns that write operations will be rejected, and directs to shippo_list_tools for operation names and shippo_describe_tool for argument shapes. It also mentions case-insensitive name lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a WRITE Shippo API operation (Create*, Update*, Delete*, *Refund, etc.). Returns the Shippo API response. WILL mutate state on the user's Shippo account.
Use this tool ONLY for operations whose kind is 'write' per shippo_describe_tool. Calling a read operation here will be rejected — use shippo_read_execute_tool for those.
Get the operation name from shippo_list_tools and its argument shape from shippo_describe_tool first. Name lookup is case-insensitive.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Write-operation short name. | |
| arguments | Yes | Operation arguments per its inputSchema. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description's statement 'WILL mutate state on the user's Shippo account' aligns and reinforces this. Additionally, the description notes case-insensitive name lookup, which provides extra behavioral context beyond the 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: three sentences that front-load the core purpose, then provide usage guidance and prerequisites. Every sentence is necessary and contributes value without redundancy.
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 presence of an output schema and annotations, the description is complete. It covers purpose, usage constraints, behavioral impact, and prerequisites. No critical information is missing.
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 100% description coverage for its two parameters. The description does not add new semantics beyond what is already in the schema for 'name' and 'arguments'. Baseline 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 purpose: executing write Shippo API operations. It provides specific examples (Create*, Update*, Delete*, *Refund) and distinguishes it from the sibling shippo_read_execute_tool by explicitly noting that reads are rejected.
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 gives explicit instructions on when to use this tool (only for 'write' operations as per shippo_describe_tool) and when not to (read operations, directing to shippo_read_execute_tool). It also outlines prerequisites: get operation name from shippo_list_tools and argument shape from shippo_describe_tool.
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.
shippo_describe_toolshippo_list_toolsshippo_read_execute_toolshippo_write_execute_toolUS shipping labels for AI agents: buy USPS/UPS/FedEx, track and refund via EasyPost.
Latin America shipping for AI agents via Envia: compare carriers, buy labels, track, cancel.
Global shipping labels for AI agents via AfterShip with your own carrier accounts.
India shipping for AI agents: Shiprocket courier serviceability, create orders, track AWB.
Add one secure layer between your agents and this server.