Bustepagamcpskill

2. Interpreting get_employee_summary()

Returns a single JSON object. Field-by-field meaning:

How to use this data

• Seniority: Calculate from data_assunzione to the current date to determine tenure-based entitlements.
• Qualifica + Livello: Together they identify the employee's exact position in the CCNL pay scale. "Quadro" is a special category between Impiegato and Dirigente with enhanced benefits (e.g. supplementary health insurance, extra notice period).
• CCNL: All salary rules (minimum pay, overtime rates, leave entitlements, seniority raise schedule) derive from this contract.

3. Interpreting get_salary_history_tool()

Returns a JSON array of monthly summaries ordered by most recent first.

Key analysis patterns

Spotting raises: Compare elementi_retributivi_totale month-over-month. A change indicates a salary adjustment (contractual renewal, promotion, seniority raise).

Identifying variable pay months: When totale_competenze is significantly higher than elementi_retributivi_totale, the difference is variable pay (commissions, bonuses, overtime, back-pay).

December anomalies: December often shows unusual figures because it includes:

• 13ma mensilita (13th month salary — mandatory Christmas bonus equal to one month's base pay)
• Year-end tax reconciliation (conguaglio fiscale) which can make deductions spike or drop
• Possibly 14ma mensilita in some CCNLs

Net pay volatility: Large swings in netto_a_pagare are normal when commissions or bonuses are paid. The tax system is progressive — higher months get taxed at a higher marginal rate.

4. Interpreting get_payslip_details_tool()

Returns the full payslip: master record + voci array (line items). This is the most complex and information-rich tool.

4.1 Master record fields

4.2 Line items (voci) — The heart of the payslip

Each voce has:

4.3 Understanding dato_figurativo (Figurative amounts)

Figurative amounts are non-cash values that appear in the payslip for tax/contribution purposes only. They inflate or deflate the taxable base WITHOUT affecting actual cash flow.

Examples from real data:

• Ass.Pol. Vita (Life insurance policy): dato_figurativo = 37.50 — The company pays a life insurance premium on behalf of the employee. The employee doesn't receive cash, but the value is taxed as a fringe benefit.
• Ass.Pol.extra prof.autom. (Extra-professional accident policy): Same logic — taxable benefit, no cash.
• Ticket elettronico (Meal vouchers): dato_figurativo = 160.00, ore_gg_num_perc = 20, dato_base = 8.00 — 20 working days × 8€ per voucher = 160€ in meal vouchers. These are tax-exempt up to the legal threshold (currently 8€/day for electronic vouchers). They appear as figurative because they're not salary.
• Smob.TFR Fonte: dato_figurativo = -1559.46 — TFR being transferred to the pension fund. Negative figurative because it's being redirected, not paid as cash.
• Ctr.fis.ded.DL47/00 c/dip: dato_figurativo = -474.17 — Tax-deductible pension fund contribution. Negative because it reduces the IRPEF taxable base.

Rule: If a voce has only dato_figurativo and both competenze and ritenute are null, it does NOT affect netto_a_pagare. It only affects the tax calculation.

4.4 Voce classification guide

Earnings (competenze)

Tracking-only items (no cash effect, no competenze/ritenute)

Figurative-only items (tax impact, no cash)

Deductions (ritenute)

Social contributions (assoggettamento = "C")

Pension fund items

Summary/informational rows (no cash effect)

These rows have both competenze and ritenute as null. They provide calculated intermediate values:

December-only year-end (conguaglio) rows

5. Interpreting search_payslip_items()

Returns grouped results + grand totals.

Important: Items that only have dato_figurativo (like Ticket elettronico) will show null for both tot_competenze and tot_ritenute, and 0 for grand totals. This is correct — they have no cash impact. To analyze meal voucher usage, look at ore_gg_num_perc (days) and dato_figurativo (total value) in the detailed payslip view instead.

Useful search keywords

6. Validation Rules & Discrepancy Detection

6.1 Monthly checksum

totale_competenze - totale_ritenute + arr_attuale - arr_precedente ≈ netto_a_pagare

Tolerance: ±0.05€. If is_valid = 0, flag immediately.

6.2 Base salary consistency

elementi_retributivi_totale should be constant across months unless:

• A CCNL renewal changed the minimum pay (usually affects all employees at once)
• A promotion/level change occurred
• A seniority raise (scatto di anzianita) was triggered by tenure milestones

Action: If it changes, explain the likely reason based on timing and magnitude.

6.3 INPS contribution validation

For each month, verify:

Contributo FPLD (voce 150): dato_base × (ore_gg_num_perc / 100) ≈ ritenute

The dato_base is the rounded INPS base. The unrounded value is in voce V01. Tolerance: ±0.02€ for standard months. In months with back-pay adjustments (voce 954), discrepancies up to ~1€ are normal.

INPS ceiling split: When the monthly INPS base exceeds the annual ceiling (massimale), contributions are split into two lines — e.g. voce 51143 (within ceiling) and 51144 (above ceiling). Both use the same rate but different base amounts. Verify each line independently. The sum of their dato_base values should approximate the full month's contribution base.

6.4 IRPEF validation (monthly)

Monthly taxable income chain (base case):

Imponibile INPS (V01 dato_base)
  − Totale ritenute sociali (voce 900 dato_base)
  + Figurative taxable items NOT in V01 (e.g. voce 891 StockO/ProfSh)
  + Non-deductible social contributions included in voce 900 (e.g. voce 044 Quadrifor)
  ≈ Impon. fiscale mese (voce I01 dato_base)

Important nuances:

• The simple formula V01 - voce 900 = I01 works for standard months with no special items.
• Stock options / profit sharing (voce 891): Taxable for IRPEF but NOT in the INPS base (V01). Their dato_figurativo must be added to the IRPEF base. Can create discrepancies of thousands of euros.
• Quadrifor (voce 044): Included in voce 900 but NOT deductible from IRPEF. Add its amount back (~25€ in January).
• 14ma/13ma mensilita (voce 082/081): When an additional month bonus is paid, the IRPEF base is split: I01 = regular income, I02 = bonus. The full check is: V01 - 900 + adjustments ≈ I01 + I02. The IRPEF on the bonus appears in I41 (not I21).
• Back-pay / arretrati (voce 266 Una tantum): Previous-year back-pay creates separate tax lanes: I03 = prior-year taxable, I48 = prior-year IRPEF (at the prior year's marginal rate). The IRPEF chain becomes: V01 - 900 + adjustments - I03 ≈ I01. The I03 amount is taxed independently via I48.
• Back-pay contribution adjustment (voce 954): May cause ~1€ discrepancy in INPS validation (check 6.3) due to retroactive contribution recalculation.
• When you detect a discrepancy, systematically check for: (1) voce 891 figurative, (2) voce I02 bonus split, (3) voce I03 back-pay split, (4) voce 044 non-deductible items, before flagging as an error.

6.5 Year-to-date progressive consistency

When comparing month N to month N-1:

imp_fiscale(N) ≈ imp_fiscale(N-1) + Impon.fiscale.mese(N)

If this doesn't hold, a retroactive adjustment or correction occurred. Flag it.

6.6 December conguaglio analysis

December is special. The payroll software recalculates the entire year's taxes:

1. I61 (Imponibile IRPEF annuo) = total annual IRPEF-taxable income
2. I64 (Imposta lorda annua) = annual gross IRPEF from tax brackets
3. I65 (Detrazioni spettanti) = annual deductions (based on 365 days if employed all year)
4. Net annual IRPEF = I64 dato_base - I65 dato_base
5. Already withheld = I68 dato_base
6. Conguaglio = Net annual IRPEF − Already withheld
   • If positive → extra deduction in December (I71 with ritenute)
   • If negative → refund in December (competenze)

Common cause of December net pay drop: Months with high commissions caused the monthly IRPEF estimate to be calculated at a lower marginal bracket. The annual recalculation pushes income into a higher bracket (e.g. from 35% to 43%), resulting in additional tax due.

6.7 TFR monitoring

Monthly TFR accrual ≈ totale_competenze / 13.5 (simplified).

If the employee directs TFR to a pension fund (voce 293 with ore_gg_num_perc = 100), the fdo_tfr_a field tracks current-year accrual but it gets periodically transferred out. Compare fdo_tfr_ap across January payslips year-over-year to see the standing balance.

6.8 Addizionali (regional/municipal surtax) pattern

These are calculated on the PREVIOUS year's income and withheld in monthly installments:

• Regional: usually 11 installments (March to January, or similar)
• Municipal: usually 9-11 installments
• Municipal advance: separate installments based on estimated current-year income

The installment number appears in ore_gg_num_perc of the rata (installment) voce. Verify that the installment amounts remain constant across months (they should be equal, since the annual total is divided evenly).

6.9 Anomaly patterns to watch for

7. Communication Guidelines

When presenting payslip data to the user:

1. Always translate Italian field names in your explanations: e.g. "netto_a_pagare (net take-home pay)", "totale_competenze (total gross earnings)".

2. Use the employee's currency: all amounts are in EUR (€). Format with 2 decimal places and thousands separators.

3. Contextualize variable pay: When commissions or bonuses appear, explain that the higher tax rate on those months is due to Italy's progressive IRPEF brackets (23% up to ~28k, 35% up to ~50k, 43% above ~50k on annualized income).

4. Be specific about figurative items: Clearly distinguish between cash items (competenze/ritenute) and figurative items (dato_figurativo only). The user should understand that figurative items affect their tax calculation but not their bank balance.

5. Flag the banca_ore field caveat: The current parser may not accurately capture this field. If the user asks about hours bank, advise checking the original PDF.

6. Explain seasonal patterns proactively:

   • January: Annual fund contributions (Quadrifor, QuAS) reduce net pay slightly
   • March onwards: Regional/municipal surtax installments begin
   • June/July: Possible 14ma mensilita (if applicable per CCNL)
   • December: 13ma mensilita + conguaglio = highly variable month

7. When validating, show your math: Don't just say "the payslip is correct." Show the calculation chain so the user can follow along.

8. Privacy: Never expose raw codice_fiscale, iban, or pdf_sha256 unless the user specifically asks. Refer to the employee by name.