irs-taxpayer-mcp

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

No annotations are provided, so the description carries full burden. While it mentions 'simplified calculation using state brackets' which provides some behavioral context, it doesn't disclose important traits like whether this is a read-only operation, what the output format will be, accuracy limitations, or whether it requires authentication. For a tax estimation tool with zero annotation coverage, this leaves significant gaps in understanding the tool's behavior.

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 appropriately concise with two clear sentences. The first sentence states the core purpose, and the second adds important qualification about the calculation method. There's no wasted language, and the information is front-loaded with the essential purpose stated first.

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 tax estimation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the output will be (dollar amount? breakdown?), accuracy limitations of the 'simplified calculation', data sources, or error conditions. With 35 sibling tools in this tax domain, the description doesn't adequately position this tool within the broader context of available tax operations.

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 three parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions 'given income and state' which aligns with the two required parameters, but provides no additional context about parameter usage, constraints, or relationships beyond what the schema already specifies.

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 clearly states the tool's purpose: 'Estimate state income tax for a given income and state' with the specific verb 'estimate' and resource 'state income tax'. It distinguishes from siblings like 'calculate_federal_tax' and 'get_state_tax_info' by focusing on estimation rather than calculation or information retrieval. However, it doesn't explicitly differentiate from 'compare_state_taxes' which might also involve estimation.

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 provides no guidance on when to use this tool versus alternatives. With multiple sibling tools like 'calculate_federal_tax', 'compare_state_taxes', and 'get_state_tax_info', there's no indication of when this estimation tool is appropriate versus those other tools. The description mentions 'simplified calculation' but doesn't explain when simplified vs. comprehensive approaches are needed.

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