Social Security COLA 2027 MCP

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the description's value-add is the calculation method: the 5/9-of-1%-per-month reduction for the first 36 early months, 5/12 after that, 2/3-of-1% delayed credits, and SSA dime rounding. This lets an agent sanity-check returned values. One gap: the 'born after 1942' qualifier hints at an unstated branch for earlier birth years, leaving that edge case opaque.

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 names the output first, then the method, with no filler. The statutory percentages are dense but each earns its place as verification context; the one weak spot is that the sentence is long enough that the 'born after 1942' clause is easy to miss.

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 identifies the return value as a monthly dollar benefit and notes dime rounding. It is missing only the output type/shape and the treatment of the pre-1943 birth case, minor omissions for a four-parameter pure 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 description coverage is 100%, so all four parameters are already documented, and the baseline is 3. The description adds only modest meaning beyond the schema — clarifying that pia is the full-retirement-age monthly amount and that claim ages run 62 to 70 — and says nothing about claim_age_months or how birth_date drives the FRA used in the math.

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 precise computation — the monthly retirement benefit at a given claiming age between 62 and 70, derived from the PIA — with both input and output semantics clear. An agent can distinguish it from calculate_cola_increase, calculate_earnings_test, and get_full_retirement_age without opening any schema, since those cover cost-of-living, work-limit, and FRA lookup tasks respectively.

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 62-to-70 age range and the requirement that the starting point be the full-retirement-age amount imply when the tool applies, but there is no explicit statement of when to use this vs. the sibling calculators or what prerequisites must be satisfied (e.g., that the FRA itself comes from get_full_retirement_age). Usage is inferable 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 establish read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it rounds down to the next lower 10 cents, reports the whole-dollar payment, mirrors SSA practice, and supplies a default year with its 3.6 percent rate. It does not describe error handling or the exact shape of the returned object.

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 sentences, front-loaded with the action, then the output semantics, then the default. Every clause carries information: rounding rule, whole-dollar display, SSA fidelity, default year and rate. Nothing is 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?

For a two-parameter, read-only calculator with no output schema, the description is nearly sufficient: it explains what is computed and how the result is rounded and displayed. It stops short of enumerating the returned fields (e.g., whether the increase amount and new benefit are both returned), which matters slightly more here because 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 coverage is 100 percent, so both parameters are already documented, making 3 the baseline. The description still adds meaning beyond the schema by tying the default year 2027 to a concrete 3.6 percent rate, which the schema does not state, and by clarifying the SSA-style rounding applied to the benefit input.

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: apply a year's Social Security COLA to a monthly benefit. That is clearly distinct from the sibling get_social_security_cola (which retrieves a rate rather than applying it), but no sibling is named, so differentiation is inferred rather than stated.

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 phrasing 'apply a year's COLA to a monthly benefit' — the agent can infer it is the tool for producing an adjusted payment amount. There is no explicit when-to-use versus get_social_security_cola, no prerequisites, and no exclusions.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the substantive withholding rules, but says nothing about how limits are sourced, that the result is an estimate, or what form the answer takes.

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 front-loaded sentence that states the computed quantity first and then the two governing rates. Every clause earns its place and 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?

For a read-only calculator with only one required parameter and full schema coverage, the description supplies the core rule needed to trust the call. The remaining gap is the absence of an output schema combined with no statement of the return value's shape (a dollar amount, possibly plus months withheld).

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 year, annual_earnings, monthly_benefit and the FRA flag in detail; the baseline is 3. The description's rate rules give meaning to why the FRA boolean matters, but that meaning is also already spelled out in 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 names a specific computation ('How much Social Security withholds under the retirement earnings test') and its inputs (a year and annual earnings), which is clearly distinct from the sibling calculators. It does not explicitly contrast itself with siblings such as get_social_security_limits or calculate_claiming_age_benefit, so it stops short of a 5.

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 formula it summarizes ($1 per $2 over the limit, $1 per $3 in the FRA year), but there is no explicit statement of when to call this versus the sibling limit or benefit calculators. The agent must infer the selection criteria from the tool names alone.

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 this as a read-only, idempotent, closed-world computation, so the description's job is to add edge-case context, and it does: it flags the January 1 rule and the day-before-birthday rule, which materially change how a given birth date is interpreted. It also enumerates the specific outputs in lieu of an output schema, though it does not give exact field names or value formats.

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 with no filler, and each clause maps to a distinct returned quantity rather than padding. The density is high enough that the enumerated outputs run together, but nothing is wasted.

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 one-parameter deterministic calculator with no output schema, enumerating the returned quantities is the key compensating detail, and the description does that plus the regulatory basis. The remaining gap is that the returned fields and their formats are described in prose rather than named, so an agent knows roughly what comes back but not the exact 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?

The single parameter is fully documented in the schema (YYYY-MM-DD with an example), so the baseline is 3. The description goes further by tying the date to date-sensitive edge cases (January 1 rule, day-before-birthday rule), which tells the agent that near-boundary birth dates produce non-obvious results and should be trusted to the tool rather than adjusted by the caller.

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 computation (full retirement age under 20 CFR 404.409) from a specific input (a birth date), and enumerates the derived values it returns (FRA date, earliest-62 month and cut, spouse percent, delayed credits, survivor FRA). It is clear what the tool does, but it never contrasts itself with the overlapping sibling calculate_claiming_age_benefit, so the boundary between 'this gives me the FRA' and 'this gives me my benefit amount' is left to inference.

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 input: supply a birth date, get FRA-related milestones back. There is no explicit statement of when to prefer this tool over calculate_claiming_age_benefit, which also works from claiming ages, nor any note about prerequisites or valid input ranges (e.g., birth years the CFR schedule covers).

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 real value beyond that: the upstream source (SSA notice in the Federal Register), the effective/payment date semantics (effective December 2026, paid January 2027), and the fact that omitting the year triggers a live external API check. It does not say what the response looks like or whether the API check can be slow or fail, but with annotations present this is adequate rather than rich.

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 dense, front-loaded sentences with almost no waste. One weakness is that the hardcoded '2027 COLA is 3.6 percent' will become stale and take up space that could have been used for sibling routing.

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?

The description is simple, with two optional parameters and no output schema. The description supplies what the return contains (the rate plus history back to 1996) and the upstream source, which is enough for an agent to call it correctly. It does not say how the values are shaped or what precision or units the history values use, but this is a minor gap.

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 both parameters are already documented in the schema, including defaults (2027, 10 years). The description mostly restates the schema's year semantics and adds only the fallback behavior when year is omitted, plus the 1996 history floor. The 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 names a specific verb and resource: it returns the Social Security COLA rate for a payable year, sourced from the SSA Federal Register notice, plus history back to 1996. That is far more specific than the name alone. It never names a sibling, though, so the boundary with calculate_cola_increase (which presumably applies the rate to a benefit amount) must be inferred from the word 'adjustment' versus 'increase'.

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 describes one concrete calling mode: with no year, it queries the Federal Register API for a newer notice. That is useful behavior, but not guidance. There is no statement of when to choose this over calculate_cola_increase or get_social_security_limits, and no explicit exclusions.

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=false, so the safety profile is covered. The description adds genuinely useful behavior context: the data provenance (Federal Register notices) and the exact set of figures returned, which effectively substitutes for the missing output schema.

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 dense sentence, front-loaded with the resource and year span before the field list. Every listed item tells the agent what data is available, so the enumeration earns its place; the inline 2027 figures are slightly wasteful but help ground the scale of the values.

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 one-optional-parameter lookup with no output schema, the description supplies the field inventory that the schema cannot, plus provenance and year coverage. An agent knows exactly what it will get back and for which years; nothing material 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% — the single year parameter already documents the 2023-2027 range, the maximum, and the 2027 default. The description restates the range and anchors it with 2027 example values but adds no new semantics such as fallback behavior for out-of-range years. 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 names the specific resource (Social Security program amounts) and scope (2023-2027, sourced from Federal Register notices), and the enumerated data items make it clearly a reference-data lookup rather than a calculator, implicitly distinguishing it from the calculate_* siblings. It lacks an explicit verb (nothing says 'Returns'), but the resource is unmistakable.

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 raw statutory figures while the calculate_* and get_*_cola siblings compute derived results, but no sentence states when to use this versus those alternatives or any prerequisite. No exclusions or routing hints are given.

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