Paycheck Calculator

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

Annotations only cover safety (readOnly/idempotent), and the description goes well beyond them: it discloses the accuracy tier per state (exact schedule for CA/NY/NJ/IL/PA/GA/NC vs. a labeled effective-rate estimate with method: "estimate"), the tax-law sources, and the data vintage (Oct 2026). That kind of pre-call expectation-setting about approximation and provenance is exactly what an agent needs before trusting the output.

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 main purpose is front-loaded, which is good, but the rest is a very dense run-on packing bracket citations, statutory dollar constants, and wage-base figures into one block with no structure. Some of those numbers (Rev. Proc. 2024-40 / 2025-32, $15,750, $176,100) do not help an agent decide whether to call the tool and could be cut or deferred to output.

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, and the description compensates by saying it returns per-period and annual figures and by flagging the output's estimate labeling and local-tax gap. For a 9-parameter, multi-jurisdiction calculator this is nearly complete; only return structure detail (field names/shape) 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 already 100%, so the baseline is high, but the description adds real tax-treatment meaning the schema only partly captures: 401(k) lowering income tax but not FICA, HSA being FICA-exempt, and the PA/NJ quirks that tax 401(k)/HSA money. It leaves the state-code-format and gross-vs-gross-per-period disambiguation to the schema, which handles those fine.

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 (calculates take-home/net pay) and pins the scope tightly: US employee, 50 states or DC, tax years 2025-2026. This clearly separates it from siblings like get_federal_tax_brackets (a lookup) and compare_states_take_home (a multi-state 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?

Usage is implied by the scope statement (single paycheck, US, no local taxes) and it explicitly excludes local taxes like NYC, which is a useful when-not. But it never names the sibling tools or says when an agent should pick compare_states_take_home or get_federal_tax_brackets instead, leaving alternative-routing 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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral disclosures: exact 2026 schedules for seven named states, labeled estimates elsewhere, nine states with no wage income tax, and the federal/FICA basis used. These accuracy caveats materially affect how an agent should present results.

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-loaded with the action and scope, followed by a short usage sentence; every clause carries information. The long parenthetical listing states and tax methods is dense but earns its place, so only minor deduction for readability.

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 9-parameter tool with no output schema, the description does well by sketching the return content (state income tax, method label, gap to best). It doesn't specify ordering/format details or error behavior for invalid state codes, which the schema only partly covers.

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% and enums are documented, so the schema does the heavy lifting. The description only restates the 2-10 state bound and the two tax years, adding no interpretation beyond the structured fields.

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 operation (run the same gross pay through 2-10 states and rank by annual take-home), the tax years supported, and what is returned. It is clearly differentiable from the sibling calculate_take_home_pay because it is inherently multi-state and comparative.

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 says 'Use it for relocation and remote-work offers,' giving a concrete decision context. It stops short of naming when-not-to-use or pointing at calculate_take_home_pay for single-state or non-comparison needs, so it's a 4 rather than a 5.

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, closed-world and non-destructive behavior, so safety is covered. The description adds meaningful context beyond annotations: the authoritative IRS sources (Rev. Proc. 2024-40, Rev. Proc. 2025-32), the OBBBA standard deduction increase, and the fact that Social Security wage base and Medicare thresholds are also returned. It does not disclose error behavior or result shape, but the annotations and explicit extra returns make this nearly complete.

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 front-loaded with the primary return values, then adds provenance and supplementary returns in a tight, information-dense package. Every clause contributes useful detail, and there is 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 two-parameter lookup tool with rich annotations and no output schema, the description is complete: it specifies what is returned (brackets, deduction, SS wage base, Medicare thresholds), the authoritative sources, and the supported years. An agent has enough information to call it correctly without needing return-value documentation.

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% and both parameters have enums and descriptions, so the schema already carries the parameter semantics. The description confirms the tax-year and filing-status inputs but adds no syntax, defaults, or special-case guidance beyond what the schema states. Baseline 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 uses a specific verb ('Returns') and names the exact resources: federal income tax brackets (rate, lower/upper bound, tax on lower brackets) plus the standard deduction, keyed to tax year and filing status. It is immediately distinguishable from the calculation-oriented siblings like calculate_take_home_pay.

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 makes the retrieval use case clear (look up brackets and deduction for a given year/filing status) and hints at scope with the two allowed years. However, it does not explicitly say when to use this rather than a sibling calculator or name alternatives, so an agent must infer the boundary.

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?

With readOnly, idempotent, and non-destructive annotations already covering safety, the description adds useful scope: gross pay only, default hours/weeks, and optional overtime at a multiplier. It stops short of specifying rounding or exact response structure, but the core behavior is well disclosed.

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 short, front-loaded with the conversion behavior, and every sentence carries useful information. There is no redundant or filler text.

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 calculator with complete parameter descriptions and safety annotations, the description supplies the necessary output scope—weekly, monthly, and annual gross pay—plus defaults and net-pay routing. 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 description coverage is 100%, so the schema already documents all five parameters. The description repeats key defaults but does not add meaning beyond the schema, such as how overtime hours interact with annualization.

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 converts an hourly wage into weekly, monthly, and annual gross pay. It also makes the direction clear against siblings such as salary_to_hourly and distinguishes gross pay from net-pay tools.

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 gives an explicit alternative for net pay: use calculate_take_home_pay. However, it does not mention salary_to_hourly for the inverse conversion or clarify when other siblings like compare_states_take_home might be relevant.

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 behavior, so the description correctly focuses on conversion assumptions: default 40 hours/week, 52 weeks/year, 2,080 total hours, and the pay-period breakdown. It discloses gross-pay-only scope and points to the net-pay alternative.

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 tightly written sentences with no filler. The core conversion and output periods are front-loaded, followed by defaults and the gross-vs-net distinction.

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 small deterministic calculator with full schema coverage and a clear safety annotation profile, the description covers the conversion outputs, default assumptions, and gross-pay limitation. No output schema exists, and the description adequately lists the returned pay periods.

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 annual_salary, hours_per_week, and weeks_per_year including defaults. The description reinforces the default hours/weeks and total 2,080 hours, but adds little beyond what the schema already 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 and resource: converts an annual salary to an hourly rate and multiple gross pay periods. It also explicitly distinguishes the output from net pay by naming calculate_take_home_pay, making its scope clear relative to a key sibling.

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 says 'Gross pay only; use calculate_take_home_pay for net,' which gives a clear condition for choosing an alternative. It does not explicitly mention hourly_to_salary, the inverse tool, but the purpose makes the direction obvious.

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