Skip to main content
Glama
dma9527

irs-taxpayer-mcp

by dma9527
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

compare_filing_statuses

Read-onlyIdempotent

Compare tax liability for the same income across filing statuses to identify the most advantageous option for your tax situation.

Instructions

Compare tax liability across different filing statuses for the same income. Helps determine the most advantageous filing status.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
taxYearYesTax year (2024, 2025, or 2026)
dependentsNoNumber of qualifying dependents
grossIncomeYesTotal gross income
itemizedDeductionsNoItemized deductions if applicable

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
textYes
errorNo
isErrorYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.0.1
    • changedInput schema / properties / taxYear / description
      Previous value: -"Tax year (2024 or 2025)"New value: +"Tax year (2024, 2025, or 2026)"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "error": {
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "suggestion": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "message",
+        "suggestion"
+      ],
+      "type": "object"
+    },
+    "isError": {
+      "type": "boolean"
+    },
+    "text": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "text",
+    "isError"
+  ],
+  "type": "object"
+}
  2. First observedv0.5.3

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the key behavioral trait that the tool compares multiple filing statuses for a fixed income and outputs the most advantageous option, which is useful beyond the annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences front-load the action and add the value proposition without redundancy. Every word contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only comparison tool with an output schema and fully documented parameters, the description is complete. It conveys the input constraint (same income) and the intended decision support, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 parameters (taxYear, grossIncome, dependents, itemizedDeductions). The description adds no parameter-specific detail beyond referring to 'same income,' so it stays at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb ('compare') and resource ('tax liability across different filing statuses') and states the goal ('determine the most advantageous filing status'). However, it does not enumerate which statuses are included or differentiate itself from the sibling compare_mfj_vs_mfs, so it lacks explicit sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The stated purpose implies when to use it: when comparing the same income under multiple filing statuses to find the best one. It provides clear context but no explicit exclusions or alternatives, so it does not reach the highest bar.

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

Deploy Server

Other Tools