Postage Stamp Price MCP

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

Annotations already establish readOnly, idempotent, openWorld, and non-destructive, so safety behavior needs no restating. The description adds value beyond that by disclosing what the response contains (nonmachinable surcharge, quantity total, Forever stamps per piece) and by capping the valid domain, which is meaningful given there is no output schema. It does not state any failure mode for out-of-range weights beyond the stated 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?

It is a single front-loaded sentence that starts with what is priced and defers coverage limits to the end, with no filler. It is dense to the point of being crammed, but every clause carries information an agent would otherwise lack.

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 five optional, fully defaulted parameters and no output schema, the description does the right extra work: it describes the returned figures and bounds the physical domain. The one shortfall is the absent sibling routing, which matters because two adjacent tools cover overlapping postage-pricing questions.

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 schema already documents every parameter including defaults and the enum. The description reinforces 'nonmachinable' with the square/rigid card example and ties quantity to a total, but that meaning is largely already present in 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?

The description opens with a specific verb+resource: retail postage for a single letter, postcard, or large envelope, priced by weight and destination, and enumerates outputs (surcharge, quantity total, Forever stamp count). Scope is unambiguous, but it never names or contrasts the siblings get_flat_rate_prices and get_stamp_price, so an agent must infer the boundary itself.

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 the stated envelope: letters up to 3.5 oz and US flats up to 13 oz, which tells the agent when the tool stops applying. However, there is no explicit routing guidance telling the agent to prefer get_flat_rate_prices for Priority/Express or get_stamp_price for pure stamp-price lookups, so the choice among siblings 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 already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the prices are retail (not commercial), are 'current', and are sourced from Notice 123, which tells the agent where the data comes from and that it is a static published reference rather than a live quote.

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 sentence that front-loads the key fact (current USPS retail prices) and then enumerates scope. The product list is long but each item earns its place by defining coverage; there is no filler or restatement of the name.

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 lookup with no output schema, the description covers what is returned and its source. The only minor gap is that it does not hint at the return shape (e.g., a list of product/price pairs or currency), which matters slightly more given there is no output schema to fall back on.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly implies the call is unfiltered and returns the full set of flat rate prices.

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 names a specific resource (USPS retail prices) and enumerates exactly which products are covered: Priority Mail Flat Rate envelopes, Small/Medium/Large/APO-FPO-DPO boxes, and Priority Mail Express Flat Rate envelopes. This is far more specific than the title alone. It does not explicitly contrast itself with the siblings calculate_letter_postage or get_stamp_price, but the product enumeration makes the boundary reasonably inferable.

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 it should call this when it needs flat rate shipping prices. There is no explicit when-to-use statement, no mention of when to prefer get_stamp_price or calculate_letter_postage instead, and no note about prerequisites or freshness of the data.

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, idempotentHint, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the data is fetched live at call time from USPS Notice 123 and carries an effective date, which tells the agent about freshness and provenance. It does not cover failure behavior if the source is unreachable, keeping it below 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?

Everything is packed into one dense sentence that leads with the headline Forever stamp price before listing the remaining rate lines. No filler, but the long comma-separated enumeration makes it slightly run-on and harder to scan than a short lead sentence plus list would be.

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 parameters, no output schema, and annotations covering the safety profile, the description's main remaining job is describing what comes back, and it does that field by field plus the effective date. The only gap is behavioral edges such as source-unavailable handling, which is minor for a simple price lookup.

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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description does not invent or reference any input options, which is consistent with the empty 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 names a concrete resource (USPS Forever stamp price) and enumerates exactly which rate lines are returned (2/3/3.5 oz, metered, postcard, large envelope, nonmachinable surcharge, Global Forever). That enumeration implicitly separates it from calculate_letter_postage, which computes postage rather than reading published rates. It stops short of naming the siblings outright, so it is clear but not maximally differentiating.

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 rather than stated: an agent can infer this is a lookup of currently published USPS rates, and 'read at call time' hints that it should be called for fresh prices. There is no explicit when-to-use vs. calculate_letter_postage or get_flat_rate_prices, and no stated conditions or exclusions. Adequate but leaves the routing decision to inference.

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