CPI Inflation Calculator

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

Annotations already declare read-only, idempotent, open-world behavior, and the description adds materially: it fetches live BLS Public Data API data for months newer than its bundled snapshot (bundled through September 2026, fetched 2026-11-03), which explains the openWorldHint in operational terms. It also discloses the October 2025 gap caused by the lapse in appropriations, a data-quality caveat an agent could not otherwise anticipate.

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 sentences, front-loaded with the core operation before the freshness and data-gap caveats. The parenthetical fetch date and bundle window are dense but earn their place as freshness evidence; minor trimming of duplicated series names would tighten it further.

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 responsibly lists what comes back: the adjusted amount, cumulative and average annual inflation, and the exact index values used. Combined with the freshness and data-gap notes, an agent has everything needed to call this correctly and interpret the result.

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 four parameters including the series enum are already documented in the schema; the description only reiterates the series options (CPI-U/CPI-W/core) without adding format or defaulting detail. Per the baseline rule, 3 is appropriate when the schema carries the parameter burden.

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 and resource: "Adjusts a dollar amount for inflation between any two periods." It also names the supported series and the 1913-to-latest range, so the operation is unambiguous. It stops short of naming a sibling such as get_inflation_rate or compare_raise_to_inflation to sharpen the distinction.

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 verb: use this when you need a dollar amount converted across periods rather than a raw rate. There is no explicit when-to-use/when-not guidance and no pointer to the closely related siblings (get_inflation_rate, calculate_social_security_cola), leaving the agent to infer selection.

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 read-only, idempotent, non-destructive and open-world, so the description correctly does not repeat safety claims. It adds genuinely new behavior: the arithmetic (prior-year Q3 CPI-W average over the year-earlier quarter, rounded to 0.1%), the data source with a live check against official BLS values, and that Q3 index values are returned alongside the result.

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 purpose and formula, then the data source and coverage in three tight sentences with no filler. The 2027 verification detail is a little dense but does real work by showing expected output shape.

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 usefully discloses what comes back (COLA percentage plus the underlying Q3 index values). Formula, data provenance, rounding precision, and historical range are all covered; only explicit alternative-tool routing 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?

Schema coverage is 100% and the single parameter is already documented as 'Year the COLA is paid, measured on Q3 of the prior year'. The description's 'covers 1976 onward' merely restates the schema minimum, adding no new syntax, format, or edge-case meaning.

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 ('Computes the Social Security cost-of-living adjustment') and pins down the exact statutory method, so it is clearly not just a generic inflation calculation. It never names or routes against the siblings (get_latest_cpi, calculate_inflation), so it falls short of full sibling differentiation.

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 year-based framing and the 'covers 1976 onward' range, and the 2027 example signals the intended input convention. There is no explicit when-to-use-this-vs-alternatives guidance, e.g. when an agent should pick this over calculate_inflation or get_latest_cpi.

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 cover safety (readOnly, idempotent, non-destructive), so the description adds the useful bits: live-checked BLS data through the latest published month, and the specific outputs returned (nominal raise, inflation, real raise, pace-keeping pay, gain/shortfall). It stops short of describing failure modes (e.g. what happens for future or invalid dates) or unit-mismatch behavior.

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 sentences, front-loaded with the operation and source, then the return payload, then applicability. No filler or restatement of the title.

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, listing the five returned figures is the right compensation, and the data recency caveat is included. An agent has enough to call it correctly; only edge-case behavior (unit mismatch, out-of-range dates) is unaddressed, which is a minor gap for a read-only calculation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents every parameter including the series enum and date formats. The description adds only modest meaning beyond that: the period must be shared between old and new pay, and the amounts can be any recurring quantity, not just salary. That is a small but real addition.

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 compound operation ("compares a pay change with CPI inflation over the same period") and even names the data source (official BLS data, latest published month). This is clearly distinct from siblings like get_inflation_rate or calculate_inflation, which supply inputs rather than doing the raise-vs-inflation comparison.

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 closing sentence gives implied applicability ("salaries, hourly wages, rents or any recurring amount"), which tells an agent the input domain. However, it never says when to prefer this over calculate_inflation or get_inflation_rate, nor any prerequisite such as matching units or period ordering.

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 establish read-only, idempotent, non-destructive, open-world behavior, so the description is not burdened with safety disclosure. It adds useful context beyond annotations: BLS CPI as the source, the specific rate measures returned, series-specific historical coverage, and the caveat about the missing October 2025 index.

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 that front-loads the core purpose and then lists the returned measures and coverage. The parenthetical caveat about October 2025 earns its place, though the sentence is somewhat run-on.

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 two-parameter tool with full schema coverage and annotations covering safety, the description supplies the important domain context: source, measures, year ranges, series differences, and a data-quality caveat. Exact response field names are not specified, but the returned components are described and no output schema exists.

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 baseline is 3. The description still adds meaning beyond the schema by clarifying that CPI-U and CPI-W cover 1914 onward while core CPI begins in 1958, and by explaining current-year behavior.

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: it returns the official U.S. inflation rate for a calendar year from BLS CPI data, including annual-average, December-to-December, and current-year 12-month rates. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as get_latest_cpi or calculate_inflation.

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 calendar-year official inflation rates and notes current-year latest 12-month behavior, but it does not explicitly say when to use this tool versus get_latest_cpi, calculate_inflation, or compare_raise_to_inflation. Guidance is therefore implied rather than 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description goes beyond them with genuinely useful disclosure: the data is checked live against the BLS Public Data API, and on failure it reports that and falls back to bundled data current through September 2026. A caller therefore knows results can be stale or degraded and that the failure is surfaced rather than silent.

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 the resource and the returned figures, followed by the usage cue and the fallback caveat. The enumerated field list is long but each item is a distinct return value, so it earns its space; the parenthetical clarifications are slightly wordy but not padded.

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 must carry the return-value burden, and it does so by naming each figure the response contains. What is missing is any sense of the response's shape or ordering, and the fallback date bound ('through September 2026') leaves it to the agent to judge staleness.

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 no parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description does not waste words inventing parameter guidance.

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?

A specific verb and resource ('Returns the most recent CPI index values published by the BLS') followed by an explicit inventory of what comes back: latest month, 12-month rate for CPI-U/CPI-W/core, NSA 1-month change, YTD change. It implicitly separates itself from get_inflation_rate via the 'inflation right now' framing, but never names a sibling or states the boundary explicitly.

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?

Gives a clear when-to-use rule: 'Use it to answer what is inflation right now.' That is a concrete selection cue rather than vague framing. It offers no when-not condition and does not name calculate_inflation or get_inflation_rate as alternatives for other shapes of question.

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