Skip to main content
Glama
ArcaTax
by Accuarion

upsert_k1_1120s

Add or replace an S-corporation Schedule K-1 (Form 1120-S) to capture shareholder ordinary income, QBI, W-2 wages, UBIA, and distributions for accurate 1040 calculations.

Instructions

Add or replace an S-corporation Schedule K-1 (Form 1120-S): ordinary income, QBI, W-2 wages, UBIA, distributions.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "k1": "<k1>"
    },
    "name": "upsert_k1_1120s"
  }
}

Input Schema

NameRequiredDescriptionDefault
k1Yes
tax_yearNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are supplied, so the description carries the full burden, and it discloses only that an existing record may be replaced. It says nothing about what gets overwritten, whether omitted fields reset to their schema defaults (a real risk here given ~18 defaulted box fields), permission requirements, or validation/error behavior. The upsert conflict semantics are the single most important behavioral fact for this tool and remain unstated.

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

Conciseness4/5

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

A single front-loaded sentence with the mutation verb and form identifier first, followed by a compact field list — no filler. The field list is slightly arbitrary (it omits fields an agent is equally likely to need) but the sentence earns its length.

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

Completeness2/5

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

This is an unannotated mutation tool whose required parameter is a nested object with about twenty mostly undocumented properties, several of which default to zero and could therefore silently clobber existing data. The description covers neither replacement keying, default-overwrite risk, nor tax-year scoping. An output schema exists, so return values need not be described, but the input-side and mutation-side gaps are substantial.

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 reported as 0% at the parameter level, so the description must compensate; it names five of the roughly twenty box fields (ordinary income, QBI, W-2 wages, UBIA, distributions), which does help an agent map intent to field names. However, it adds no meaning for the required nested 'k1' wrapper, the 'id' used for replacement, 'tax_year' (default 2026), 'owner', 'ownership_pct', or 'material_participation', and gives no units or sign conventions.

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?

The description names a specific verb pair ('Add or replace') and a specific resource (S-corporation Schedule K-1, Form 1120-S), and enumerates representative fields (ordinary income, QBI, W-2 wages, UBIA, distributions). This clearly separates it from siblings such as upsert_1099, upsert_schedule_c, and upsert_w2 by tax form. It stops short of explicitly excluding a partnership 1065 K-1, so it is not a full 5.

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

Usage Guidelines2/5

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

There is no guidance on when to use this versus the other upsert_* tools beyond the form name, and no prerequisites are stated (e.g. whether a filing profile or return must already exist). The 'replace' half of the upsert is left unexplained — an agent cannot tell what key triggers replacement or when it should supply an id. Usage is only inferable from the tool name.

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