compare_statesNet pay on the same salary in several states, ranked best-first, with each state's gap to the best one.
| Name | Required | Description | Default |
|---|---|---|---|
| salary | Yes | Gross annual salary in US dollars | |
| states | Yes | 2 to 51 states/DC | |
| filingStatus | No | Filing status. Defaults to "single". "single" also covers married-filing-separately. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It does mention the ranking and gap output, but it does not disclose calculation assumptions (e.g., which taxes are included, use of standard deductions) or limitations. This is moderately transparent but leaves room for ambiguity.
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 sentence that immediately conveys the tool's purpose and output format. It contains no filler or redundant wording, making it highly concise and well-structured.
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 tool with three parameters and no output schema, the description is fairly complete: it explains the output ranking and gap, and the schema covers parameter details. While it lacks notes on tax assumptions, this is not critical for selecting or invoking the tool correctly.
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 does not add parameter-specific meaning beyond 'same salary' and 'several states,' both of which are already evident from the schema's property descriptions. No extra semantics are provided.
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 exactly what the tool does: compares net pay on the same salary across multiple states, and specifies the output as a best-first ranking with gap to the best. This clearly distinguishes it from sibling tools like compute_take_home (single state) and get_state_rates (rates only).
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 tool's use case is implied by its name and description—comparing take-home across several states—but it does not explicitly mention when to use it instead of siblings like compute_take_home or get_state_rates. No exclusion criteria or conditional guidance is provided.
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.
Each tool has a distinct focus: multi-state comparison, bonus withholding, single-state full breakdown, and reference rates. compute_take_home and get_state_rates overlap slightly on state tax details, but the purpose is clearly different (calculation vs. reference).
All tool names follow a consistent verb_noun pattern: compare_states, compute_bonus_withholding, compute_take_home, get_state_rates. The verbs 'compare', 'compute', and 'get' are all clear and consistent in style.
Four tools is well within the ideal range for a focused paycheck/tax calculator. Each tool serves a distinct, necessary function with no redundancy or bloat.
The set covers the core workflows: single-state take-home, multi-state comparison, bonus-specific withholding, and state rate lookup. Minor gaps exist, such as no support for hourly or irregular pay calculations, but the main domain is well covered.