EasyPost MCP by usefulapi

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

Annotations only say readOnlyHint=false and destructiveHint=true; the description goes further by disclosing real financial cost (account balance charge), irreversibility, and the remediation route via refund. It also pins the underlying endpoint and body shape, which annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the action and immediately followed by the warning; every clause carries information (cost, irreversibility, escape hatch, rate source, API endpoint). Nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema the description would ideally say what a successful purchase returns (label URL/format, tracking code), since that is the artifact the caller needs next. Everything else an agent needs to call it correctly — cost, prerequisites, alternatives, params — is present.

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 rate_id description already says where the id comes from, so the description's 'pick a rate_id from...' largely restates the schema. It adds little about the string format of insurance or shipment_id beyond what the schema notes ('shp_...', '"249.99"'). Baseline 3 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?

Specific verb ('PURCHASE a shipping label') plus resource (shipment/rate) and the exact API operation, which cleanly separates it from easypost_create_shipment (which only produces rates) and easypost_refund_shipment (which reverses this). An agent can pick it out of the sibling list without opening a schema.

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 states the precondition (a rate_id must come from easypost_create_shipment or easypost_get_shipment), the consequence (charges the account balance, irreversible), and the alternative path for reversal (easypost_refund_shipment). That is an explicit when/when-not plus named siblings.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is partly given. The description adds the critical behavioral fact that no charge or label purchase occurs here, which an agent cannot infer from annotations alone. It stops short of discussing auth or idempotency, so not a 5.

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-loads the create-and-rate action, then the key negative constraint, then the API endpoint. Every clause earns its place with no 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 nested objects, no output schema, and 5 params, the description covers inputs, behavior, the non-charge guarantee, a return hint (available rates), and the API route. It could say more about the optional carrier_accounts filter for rating scope, but it is largely 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 description coverage is 100% with detailed nested field docs (weight in OUNCES, ISO country codes, etc.), so the schema carries the parameter burden. The description only restates the three required inputs and adds no format or syntax detail beyond the schema, so baseline 3 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?

States a specific verb (Create a shipment) and resource, names the exact required inputs (to_address, from_address, parcel), and clarifies scope: it returns rates rather than buying labels. This distinguishes it from easypost_buy_shipment without opening either schema.

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 use it (to get rates) and when not to (it does NOT purchase a label or charge the account), and names the alternative easypost_buy_shipment for buying. Nothing is left to inference.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the write-but-non-destructive profile is already covered. The description adds genuinely useful context in 'No charge' (billing behavior) and the return of current status, but says nothing about idempotency or what happens if a tracker for the same code already exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded sentences with no padding; the purpose and cost note come first. The trailing 'API: POST /trackers (body { tracker })' is marginally useful but leans on internal API jargon that adds little for tool selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly compensates by stating that it returns the tracker with current status. Nothing critical is missing for a simple two-param creation call, though duplicate-handling behavior would round it out.

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 both parameters (carrier, tracking_code) are already documented including the carrier disambiguation hint. The description only restates that it works via carrier tracking code, adding no syntax or format detail beyond the schema — baseline 3 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?

States a specific verb+resource ('Start tracking a package by its carrier tracking code') and clarifies the operation creates a tracker rather than fetching one. However, it never names the obvious sibling easypost_get_tracker, so the agent must infer the create-vs-retrieve distinction from the name alone.

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?

Implies usage (you have a tracking code and want to begin tracking), and 'No charge' hints this is a safe/cheap call. But there is no explicit when-to-use guidance or contrast against easypost_get_tracker / easypost_list_trackers.

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

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

readOnlyHint=true already tells the agent this is a safe read, lowering the bar. The description adds one piece of real context beyond that ('including verification details') and names the underlying endpoint, but says nothing about error behavior for unknown ids or whether the lookup costs an API call.

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 short sentences, front-loaded with the action and resource, with the endpoint reference as trailing detail. Nothing is padded or redundant.

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, and the description partially compensates by noting that verification details are included in the response. For a one-parameter read tool the definition is nearly complete; only the failure mode for an invalid id is unaddressed.

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 single 'id' parameter is documented with an example prefix ('adr_...'), so the schema already carries the semantics. The description only restates 'by id' and adds nothing about format or validity, making 3 the correct 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?

Specific verb ('Retrieve') plus resource and scope ('a single address by id'), which cleanly distinguishes it from sibling easypost_list_addresses. The parenthetical 'including verification details' further narrows what this returns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'by id' — use it when you already hold an address id — but the description never states when to prefer this over easypost_list_addresses or easypost_verify_address, both of which are plausible alternatives. No exclusions or prerequisites are given.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description's job is to add context, which it does: it discloses the conditional nature of postage_label ('if purchased') and tells the agent what fields come back. It stops short of noting behavior for unknown ids or any rate-limit/auth characteristics.

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?

One tightly constructed sentence front-loads the action and resource, then adds the notable return fields and the underlying endpoint with no filler. Nothing is padded or redundant.

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 one required parameter, full schema coverage, and no output schema, the description carries the return-value burden and does so by naming the key fields. It is essentially complete, missing only error/not-found behavior for an invalid id.

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 a single parameter with 100% schema description coverage, so the baseline is 3. The description restates the id-based lookup but adds no format, prefix, or lookup guidance beyond the schema's own 'shp_...' example.

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 states a specific verb (Retrieve), a precise resource (a single shipment by id), and enumerates the meaningful payload (rates, tracking_code, postage_label). This clearly separates it from easypost_list_shipments and the write siblings such as buy_shipment or refund_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?

Usage is implied by 'by id' and the sibling set — fetch a known shipment id after creation — but there is no explicit when-to-use statement, no pointer to list_shipments for discovering ids, and no stated condition for when not to call it.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, and the description usefully adds that the response includes current status and tracking_details history. It stops there, disclosing nothing about rate limits, authentication, or what a missing/invalid id returns.

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 compact sentences, front-loaded with the action and return contents, with the endpoint appended as a terse routing aid. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only single-fetch tool with no output schema, the description compensates by naming the returned fields (status, tracking_details history). A minor gap remains around error/empty-result behavior, but nothing critical is missing for correct invocation.

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% with a single documented parameter (id, e.g. trk_...), so the schema already carries the semantics. The description confirms id-based lookup but adds no format or syntax detail beyond what the schema provides.

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?

States a specific verb (retrieve) and resource (a single tracker) scoped by id, and even names the underlying endpoint GET /trackers/{id}. The word 'single' implicitly contrasts with the sibling easypost_list_trackers, so an agent can distinguish them without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the tool for fetching one known tracker id, and that easypost_list_trackers is the alternative when no id exists. No explicit when/when-not or prerequisite (e.g., tracker must already exist from easypost_create_tracker) is stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds that results are paginated, which is useful behavioral context, but says nothing about ordering, cursor semantics, or result volume. With annotations carrying the safety load, this is an adequate but not rich disclosure.

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 brief sentences, front-loaded with the operation and scope; nothing is padded or repeated. The endpoint reference is compact and informative for an agent that may need to map to API docs.

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, zero-required-param list tool with full schema coverage and no output schema, the description covers enough to invoke it correctly. There is no output schema, so the description need not explain returns, though it could note the address fields returned.

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 after_id, before_id, and page_size are fully documented in the schema itself. The description only alludes to pagination generically and adds no syntax or semantic detail beyond what the schema already provides, which is the baseline-3 case.

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 states a specific verb and resource ('List saved addresses on the account') plus the underlying endpoint, so the agent knows exactly what the tool does. It does not, however, explicitly distinguish itself from sibling easypost_get_address or easypost_list_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?

Usage is only implied by the word 'List' and the account scope; there is no statement of when to reach for this tool versus easypost_get_address (single lookup) or the other list tools. No exclusions or prerequisites are given.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds one genuinely useful behavioral trait — results are returned most recent first — plus the underlying GET /shipments endpoint, but says nothing about pagination mechanics (cursor semantics for after_id/before_id) or result limits.

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 filler, with the primary purpose and result ordering front-loaded before the endpoint detail. Every clause carries 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 zero-required-parameter list tool with a fully documented schema and readOnlyHint, the description covers purpose, ordering, pagination existence and filters. Only the pagination mechanics are left implicit, which is a minor gap given no output schema exists to explain result shape.

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 all six parameters are already documented with format context (ISO 8601 bounds, max page size, cursor ids). The description only refers to 'optional filters' generically and adds no meaning beyond the schema, which is the baseline case.

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?

States a specific verb and resource ('List shipments on the account') plus ordinality and pagination/filter behavior, which clearly distinguishes it from get_shipment and the create/buy siblings. It stops short of explicitly naming sibling alternatives, so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the collection-read tool while get_shipment fetches one record. There is no explicit 'use this when...' guidance or exclusion criteria against the other list_* tools (addresses, trackers).

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

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

The readOnlyHint annotation already establishes that this is a non-mutating read, so the bar is lower. The description adds the underlying API call (GET /trackers), which is mildly useful, but says nothing about pagination behavior, default page size, or result volume — meaningful gaps for a list operation.

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?

A single efficient sentence with the filter semantics front-loaded, followed by the raw API endpoint. Nothing is padded, though the API path line carries little decision value for an agent.

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?

There is no output schema, so the description would ideally characterize the returned tracker list or pagination semantics, and it does not. For a simple read-only list tool this is adequate but leaves the agent without return-shape or paging expectations.

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 all three parameters are already documented in the schema. The description only restates that tracking_code and carrier act as filters and omits page_size entirely, adding no syntax or format detail beyond the schema. Baseline 3 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?

States a specific verb and resource ('List package trackers') plus the optional filter dimensions, so the operation is unambiguous. It does not name or differentiate itself from the sibling easypost_get_tracker (single vs. list), which is the main remaining gap.

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 only says the listing is 'optionally filtered by tracking_code or carrier' — it never states when to use this list tool versus easypost_get_tracker or easypost_create_tracker, nor any pagination caveat. Usage is left entirely to inference from the name.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds genuinely new context: that this reverses a purchase and that approval is not guaranteed and depends on carrier/label age. It does not say what the returned refund state looks like or whether repeat calls are safe, but the non-deterministic outcome is the key trait an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact clauses with no waste; the action, the risk warning, and the endpoint are each front-loaded in order of importance for an agent deciding whether to call it.

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 single-parameter destructive mutation with no output schema and no annotations gap, the description covers purpose, risk, and endpoint. What is missing is only the shape of the outcome (e.g., pending-refund status), which is minor since no output schema exists to imply it.

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 single id parameter is already documented with an example format in the schema. The description adds no syntax or constraint beyond what the schema provides, so the baseline 3 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?

States a specific verb pair (refund/void) and resource (purchased shipping label), which is clearly distinct from buy/create/get siblings. An agent can route here without opening the schema.

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?

Identifies the triggering context (a purchased label that needs reversing) and notes that success is conditional on carrier and label age. It doesn't name an explicit alternative or state when not to use it, but the operation is unambiguous within the sibling set.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description is consistent with that ('Create' = write, non-destructive). It adds value beyond annotations by disclosing the cost profile ('No charge') and the underlying API call, though it omits idempotency/dedup behavior for repeated address creation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded sentences with no filler: capability, cost, and endpoint. Every clause 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?

With no output schema, the description correctly takes on the return-value burden by naming deliverability and normalized/corrected fields. For a 10-parameter write tool it leaves the parameter story thin, but the core transactional picture (what it does, what it returns, what it costs) is 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 description coverage is only 40% across 10 parameters, so the description must compensate, and it largely does not. It hints at the API body shape ({ address, verify: ["delivery"] }) but never maps this to the actual input fields or explains the undocumented ones (name, email, phone, street2, company).

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?

States a specific verb+resource ('Create and verify a US or international address') plus the outcome ('returning deliverability and normalized/corrected fields'), which is far more informative than the bare title. It does not explicitly differentiate itself from siblings like easypost_get_address or easypost_list_addresses, though the 'verify' capability is implicitly unique in the set.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied (verify before shipping) and the 'No charge' note gives an incentive to prefer this over other flows, but there is no explicit when-to-use statement, no exclusions, and no named alternative for address validation. The agent must infer context.

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