MLP Tax Computation Engine

k1_basis_multi_year

Read-onlyIdempotent

Computes a running adjusted partner basis across multiple years of Schedule K-1 data, per IRC §705 (basis computation), §731(a)(1) (gain on distributions exceeding basis), §751(a) (accumulated ordinary recapture), §752 (liability share allocation across years), §704(d) (suspended-loss carryforward), and §1014(a) (step-up if death today). Returns year-by-year basis trajectory, accumulated §751 recapture estimate, projected zero-basis year, §1014 step-up value if death today, and the broker-basis gap — the dollar amount by which a typical 1099-B understates true IRS-adjusted basis.

Use when: User holds a direct MLP position (EPD, ET, MPLX, WES, PAA, NRP, USAC, SUN) across multiple consecutive tax years, has K-1s for those years, and wants to track adjusted basis year over year, identify the zero-basis year, quantify the gap between broker-reported basis and true IRS basis, or project §1014 step-up value if death occurred today.

Don't use for: Single-year basis worksheet from one K-1 — use k1_basis_compute. Long-horizon forward projection from default assumptions when no actual K-1s are in hand — use mlp_projection. 1099-DIV ETFs (AMLP, MLPX, AMZA — RIC structure, no K-1, no basis-erosion mechanism; use a standard cost-basis calculator). Multi-position portfolio basis tracking — this tool handles one position per call.

Limitations: Single position, single lot — for multi-lot or multi-position basis tracking with optimal sell ordering, see lucasandersen.ai. Federal-level only — does not include state-level basis adjustments. Accumulated §751 recapture is estimated across years; actual depends on the partnership's hot-asset disposition schedule and any year-specific §751(b) events. Full multi-year basis reconstruction with a CPA-ready workpaper is available at https://lucasandersen.ai/private-partnership-k1-basis?src=mcp&tool=k1_basis_multi_year&surface=description.

Maintained by Lucas Andersen, MS Finance, with direct positions in major midstream MLPs. Methodology auditable at lucasandersen.ai/methodology.

Input Schema

TableJSON Schema

Name	Required	Description
`units`	Yes
`ticker`	Yes
`k1_years`	Yes	Array of annual K-1 data, one per year held (max 50)
`tax_bracket`	No
`purchase_year`	No
`purchase_price`	Yes

TDQS

A4.1/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is a safe, repeatable computation. The description adds limitations (single position, single lot; federal-level only; estimated recapture) that go beyond annotations. However, it doesn't disclose data retention, how K-1 data is used ephemerally, or whether state adjustments are ignored. With strong annotations, the description adds moderate behavioral context.

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?

The description is lengthy but well-structured with clear sections: what it does, when to use, exclusions, limitations, and attribution. It front-loads the core computation and IRC references. The 'Maintained by' and URL at the end add verbosity, but every section serves a purpose. Could trim the IRC citation list slightly, but overall efficient.

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

Completeness4/5

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

Given the tool's complexity (6 parameters, multi-year K-1 inputs, no output schema), the description provides a full picture: inputs, outputs, use cases, exclusions, and limitations. The only gap is no explicit mention of error handling (e.g., missing years, invalid box values) or performance with max 50 years. Combined with strong annotations, it is nearly complete.

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 17%, which is low, and the description does not explain individual parameters like k1_years.box1, box11, liability_increase/decrease, or tax_bracket beyond their names. The description compensates by listing what the tool outputs (basis trajectory, recapture estimate, zero-basis year, step-up value, broker-basis gap), but parameter-level guidance is missing. Baseline 3 is appropriate given low coverage.

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

Purpose5/5

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

The description clearly states the tool computes a running adjusted partner basis across multiple years of Schedule K-1 data, citing specific IRC sections. It distinguishes itself from siblings like k1_basis_compute (single-year) and mlp_projection (forward projection without actual K-1s), and lists partner-level alternative tools for multi-position tracking.

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

Usage Guidelines5/5

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

The 'Use when' section explicitly tells when to invoke (direct MLP position with multiple K-1s) and the 'Don't use for' section lists four specific alternatives (k1_basis_compute, mlp_projection, standard cost-basis calculator, lucasandersen.ai for multi-position). This provides clear context and exclusions.

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

All MLP Tax Computation Engine tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation5/5

Each tool targets a very specific and distinct use case: single-year basis, multi-year basis, long-term projection, estate planning, sell-vs-hold decision, and reference data lookup. The descriptions clearly state when to use each and (crucially) when not to, making selection unambiguous.

Naming Consistency4/5

Tool names mostly follow the pattern of domain prefix followed by the specific operation (e.g., k1_basis_compute, mlp_projection, mlp_sell_vs_hold). The naming is clear, though 'mlp_estate_planning' is a full phrase rather than verb_noun, which is a minor deviation from an otherwise strong pattern.

Tool Count5/5

With 6 tools covering basic reference, single-year basis, multi-year basis, projection, estate planning, and sell-vs-hold decision, the count is well-scoped for the domain. Each tool serves a clear purpose, and there is no bloat or missing critical functionality for the stated MLP tax and estate analysis use cases.

Completeness5/5

The tool set provides complete coverage of the MLP tax and estate planning lifecycle: retrieving reference data, computing single-year and multi-year basis, projecting future tax scenarios, comparing sell vs. hold, and analyzing estate step-up benefits. All major decision points and IRC sections are addressed, leaving no obvious gaps for a direct MLP holder.

Resources

Need Help?