calculate_cola_increaseApply a year's Social Security COLA to a monthly benefit. Rounds down to the next lower 10 cents and shows the whole-dollar payment, as SSA does. Default year 2027 (3.6 percent).
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Year the COLA is first paid. Default 2027. | |
| monthly_benefit | Yes | Current monthly benefit in dollars, for example 2008. |
Changes observed during successful MCP inspections.
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.
Add one secure layer between your agents and this server.