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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new operational context: it is free, rate-limited to 200 calls per day per visitor, and scoped to tax year 2026. The 'no side effects' clause is redundant with the annotations but not contradictory.

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 verb and the computed components, then the differentiator and limits. Efficient overall, though the trailing 'no side effects' phrase restates what the annotations already guarantee and could be dropped.

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?

No output schema exists, but the description enumerates the tax components computed, which implicitly tells the agent what the result covers. Rate limits, tax year and state scope are all present; only the exact response shape (e.g., whether a per-tax breakdown and net figure are both returned) is left unstated.

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%, with state, salary, pretax401k and filingStatus all documented including the enum values and default, so the baseline is 3. The description adds only marginal parameter-level meaning (state rules vary, nine states have no income tax) and says nothing about pretax401k or filingStatus 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?

States a specific verb (calculate), an exact resource (net/take-home pay from gross US salary) and enumerates the components computed (federal income tax, Social Security to the wage base, Medicare with surcharge, state income tax). This clearly separates it from siblings like get_tax_brackets (bracket lookup only) and get_salary_percentiles.

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 one directional instruction ('use this instead of estimating') and justifies it with the fact that state rules differ and nine states levy no income tax. However, it never routes the agent between this tool and its actual siblings (get_tax_brackets, compare_cost_of_living), so when-to-use-vs-alternative guidance is implied rather than explicit.

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