• Completion of income tax calculation using the

  /income-tax

  skill
• Completion of financial statements (P/L, B/S) using the

  /settlement

  skill
• Completion of consumption tax calculation using the

  /consumption-tax

  skill (if applicable)

• shinkoku.config.yaml

  is properly configured
• One of the browser automation tools is available (see "Browser Automation Method Selection" below)

browser_subagent

browser_subagent

• "Open https://www.keisan.nta.go.jp/kyoutu/ky/sm/top_web#bsctrl"
• "Click the 'Yes' radio button for 'Do you have a My Number Card?'"
• "Enter '1' into the input field with name='sonekiKeisansyoFromMonth'"

etax-stealth.js

1. Set environment variable:

   PLAYWRIGHT_MCP_INIT_SCRIPT=skills/e-tax/scripts/etax-stealth.js

2. Launch browser:

   playwright-cli -s=etax open <url> --headed --browser=chrome

3. Execute subsequent commands with

   -s=etax

   session specification

1. Load

   shinkoku.config.yaml

   using the Read tool
2. If the file does not exist, guide the user to execute the

   /setup

   skill and exit
3. Understand configuration values:
   • Taxpayer profile (name, address, My Number, etc.)
   • Business information (trade name, industry type, etc.)
   • Filing method (e-Tax/mail/counter)

1. Load

   .shinkoku/progress/progress-summary.md

   using the Read tool (if it exists)
2. Load the following handover documents using the Read tool (if they exist):

   • .shinkoku/progress/06-settlement.md

     — Settlement results (P/L/B/S data)

   • .shinkoku/progress/07-income-tax.md

     — Income tax calculation results

   • .shinkoku/progress/08-consumption-tax.md

     — Consumption tax calculation results

   • .shinkoku/progress/02-assess.md

     — Taxability determination results
3. Check

   status

   in

   .shinkoku/progress/10-etax.md

   :
   • If

     status: interrupted

     → Follow resumption procedure in "Interruption/Resumption Protocol" below
   • If

     status: completed

     → Notify user that filing is complete and confirm intention to re-execute
4. If calculation results do not exist yet, guide user to execute

   /income-tax

   and

   /settlement

   first

1. Confirm input contents of current step — Check for unsaved input
2. Guide to download .data file — Display the following using AskUserQuestion:

We recommend saving the input data from the preparation corner as a .data file.
Click the "Temporarily save input data" button at the top of the screen (or the "Save input data up to this point" link at the bottom of the page)
and download the file.

Please select "Downloaded" once the download is complete.

• Options: "Downloaded" / "Skip (do not save)"
• If "Skip" is selected, warn the user that they may have to start over from the beginning next time

1. Record progress file — Output to

   .shinkoku/progress/10-etax.md

   in the following format using the Write tool:

---
step: 10
skill: e-tax
status: interrupted
last_completed_step: "{Last completed step number (e.g., 3)}"
last_url: "{Browser URL at time of interruption}"
data_file_saved: {true/false}
interrupted_at: "{Current date YYYY-MM-DD}"
fiscal_year: {tax_year}
---

• Last completed step: Step {N}
• URL at interruption: {URL}
• .data file saved: {Yes/No}

1. Re-execute the

   /e-tax

   skill
2. If you have a .data file, resume from "Create using saved data"
3. If you don't have a .data file, start over from step 0

4. **Notify user of completion of interruption** — Guide user on how to resume next time and exit

status: interrupted

.shinkoku/progress/10-etax.md

1. Read interruption information (

   last_completed_step

   ,

   data_file_saved

   )
2. Display the following using AskUserQuestion:

Your previous e-Tax input was interrupted at step {N}.

Please select how to resume.

• Options:
  • "Resume from .data file" (display only if

    data_file_saved: true

    )
  • "Start over from the beginning"
  • "Discard interruption record and exit"

1. If resuming from .data file:
   • Access the top page of the Tax Return Preparation Corner
   • Select "Create using saved data" → "Resume creation"
   • Guide user to upload the .data file
   • After loading is complete, resume from the step following

     last_completed_step

2. If starting over from the beginning:
   • Start normally from step 0

1. "Do you have a My Number Card?" → Click "Yes" radio button
2. "Do you have a smartphone or IC card reader/writer compatible with My Number Card reading?" → Click "Yes"
3. Click "Use smartphone"
   • JS:

     doSubmitCSW0100('1','3','/ky/sm/csw0100_myno_qr')

• Income Tax →

  doSubmitCMW0900(1,'25')

• Financial Statement/Income Statement (+ Income Tax) →

  doSubmitCMW0900(2,'25')

  ← If you have business income
• Consumption Tax →

  doSubmitCMW0900(3,'25')

• Gift Tax →

  doSubmitCMW0900(4,'25')

• With business income → "Financial Statement/Income Statement (+ Income Tax)"
• Without business income (salary only, etc.) → "Income Tax"
• Consumption tax is created separately after income tax completion

QR code authentication screen is displayed.
Read the QR code with your smartphone's My Number Portal app
and authenticate with your My Number Card.

Please select "Authentication completed" once authentication is done.

• Options: "Authentication completed" / "QR code is not displayed"
• If "QR code is not displayed" is selected, refer to ⚠️ Notes for Playwright CLI use below for troubleshooting
• Do not perform any browser operations or screen transitions until user selects "Authentication completed"

etax-stealth.js

PLAYWRIGHT_MCP_INIT_SCRIPT

getClientOS()

'Windows'

window.getClientOS = function() { return 'Windows'; };
displayQrcode();

⚠️ Native dialog warning: If screen does not transition after clicking "Next", a native dialog (alert/confirm) may be displayed. Refer to "Detection and Handling of Native Dialogs" in Technical Insights.

• Blue Return Financial Statement ← For blue return filers
• Income Statement (For white return filers)
• Blue Return Financial Statement (For cash basis)

/kessan/ac/aa0201

• uriageKingaku1

  ~

  uriageKingaku12

  : Monthly sales

• siireKingaku1

  ~

  siireKingaku12

  : Monthly purchases

• kajisyohi

  : Household expenses, etc.

• zatusyunyu

  : Miscellaneous income

uriageKingakuGokei

siireKingakuGokei

• kurimodosiNiniKamoku1

  /

  kurimodosiNiniKingaku1

• kurimodosiNiniKamoku2

  /

  kurimodosiNiniKingaku2

• senjusyaKyuyoTotalGokei

  (hidden, separate screen via "Input" button)

• kasidaoreKuriireGokei

  (hidden)

• disp_aoiroKojomaeSyotokuKingaku

  = Sales - Cost of goods sold - Expenses + Carryback amounts - Dedicated employee salaries, etc.

aoiroTokubetuKojoSentakugaku

⚠️ Native dialog warning: If you select ¥650,000 and proceed, a native dialog with error KS-E10089 (e-Tax filing required) will be displayed for paper filing. If screen does not transition, confirm with user whether dialog is displayed.

fusainobuTaisyohyoDetailDataList[N].kisyuKingaku

.kimatuKingaku

⚠️ Native dialog warning: If you click "Next" after B/S input and total assets do not equal total liabilities, a native dialog with error KS-E40003 will be displayed. If screen does not transition, confirm with user whether dialog is displayed.

/kessan/ac/submit/ac0600

⚠️ Native dialog warning: When clicking this button, a native dialog with warning KS-W10035 (Have you confirmed printing?) may be displayed. If screen does not transition, confirm with user whether dialog is displayed and guide them to click "OK".

⚠️ Native dialog warning: If screen does not transition after clicking "Next", a native dialog (alert/confirm) may be displayed. Refer to "Detection and Handling of Native Dialogs" in Technical Insights.

inOutDto.kyuy

inOutDto.jgyoEgyoTo

inOutDto.jgyoNogyo

inOutDto.fdosn

inOutDto.ztsGyomSnt

inOutDto.kotkNnknKgyoNnknEtc

inOutDto.tasyku

inOutDto.hatoKbshkJyotRsh

inOutDto.skmnTrhk

inOutDto.ichj

• Company employee + side business (business income):

  kyuy

  +

  jgyoEgyoTo

  +

  ztsGyomSnt

  (if cryptocurrency)
• Salary income only:

  kyuy

• Social insurance premium deduction (displayed as "Input done" if already input via withholding tax statement)
• Small business mutual aid premium deduction (iDeCo, etc.)
• Life insurance premium deduction
• Earthquake insurance premium deduction
• Casualty loss deduction / Disaster relief
• Medical expense deduction
• Donation deduction (including hometown tax payment — one-stop special case also needs input)

• Spouse (special) deduction
• Dependent deduction / Special deduction for specified relatives
• Widow/single parent deduction
• Working student deduction
• Disability deduction
• Basic deduction (automatic calculation display)
• Special deduction for housing loans, etc.
• Special deduction for seismic retrofitting of housing, etc.
• Estimated tax payment amount
• Carryforward loss amount

• Income amount/income amount (by income type)
• Total income deductions
• Taxable income amount (rounded down to nearest ¥1,000)
• Tax amount on above (using tax table)
• Net income tax amount
• Special reconstruction income tax amount (2.1% of base income tax amount)
• Amount of income tax and special reconstruction income tax
• Withholding tax amount
• Declared tax payment amount (rounded down to nearest ¥100) / Tax refund amount

inOutDto.nofHoho

• Financial institution name, branch name, account number, account holder name

⚠️ Native dialog warning: If screen does not transition after clicking "Next", a native dialog (alert/confirm) may be displayed. Refer to "Detection and Handling of Native Dialogs" in Technical Insights.

doSubmitCSW0900(3,'25')

• 20% Special Provision:

  /syouhi/at3600/inputEigyo.htmj

• Simplified Taxation:

  /syouhi/ak3600/inputEigyo.htmj

• Standard Taxation:

  /syouhi/ai3600/inputEigyo.htmj

uriageWari

menzeiUriageWari

hikazeiUriageWari

jigyoFukazeiUriageWari

kazeiUriage624PercentWari

uriageTaikaKeigen.uriageTaika624Percent

uriageTaikaKeigen.uriageTaika78Percent

kasidaoreKeigen.occurredKasidaore624Percent

kasidaoreKeigen.occurredKasidaore78Percent

kasidaoreKeigen.recoveredKasidaore624Percent

kasidaoreKeigen.recoveredKasidaore78Percent

kasidaore.occurredKasidaoreAns

/syouhi/ak2140/submit.htmj

• Standard calculation
• Special calculation (2-type special case/3-type special case/75% special case)

• "Excessive input tax credit adjustment tax amount"
• "Taxable sales ratio" section (Consideration for transfer of taxable assets, etc. / Consideration for transfer of assets, etc.)

• 20% Special Provision:

  /syouhi/at1400/submit.htmj

• Simplified Taxation:

  /syouhi/ak1400/submit.htmj

• Standard Taxation:

  /syouhi/ai1400/submit.htmj

nofuHohoType

nozeitiKubun

nozeitiZipCode1

nozeitiZipCode2

nozeitiPrefectureCode

municipalityCode

nozeiti1ElaseMunicipal

prefectureCode

sinkokuZeimusyoCode

simeiKanaSei

simeiKanaMei

simeiKanjiSei

simeiKanjiMei

myNumber1

myNumber2

myNumber3

telNumber1

telNumber2

telNumber3

nozeitiPrefectureCode

prefectureCode

⚠️ Native dialog warning: When exiting the consumption tax corner, two-stage native dialogs are displayed —

#otherTax

(Do you want to create other return forms?) and

#end

(Are you sure you want to exit?). If screen does not transition, confirm with user whether dialogs are displayed and guide them to click appropriately.

Two-stage gate structure: Step 5.5 is the "decision gate for whether to proceed to the transmission phase". Step 6-3 is the "operation gate immediately before the transmission button (AI does not transmit, user transmits manually)". Transmission is not executed unless both gates are passed.

Please select the next operation.

• Options:
  • "Proceed to digital signature and transmission" → Proceed to Step 6
  • "Review input contents" → Confirm step to review and return to applicable step
  • "Stop here" → Follow interruption procedure in Interruption/Resumption Protocol and exit

Proceeding to digital signature screen.
Perform digital signature with your My Number Card.

Please select "Signature completed" once signature is done.

• Options: "Signature completed" / "Problem occurred during signature"
• Do not perform any browser operations until user selects "Signature completed"

1. Read contents of confirmation page on browser
2. Report main items to user (income, income, tax amount, payment/refund amount, etc.)
3. Report comparison results with shinkoku calculation results

Pre-transmission declaration content confirmation page is displayed.
Please confirm the above contents.

If there are no issues, click the "Execute transmission" button on the screen
with your own operation.

Please select "Transmission completed" once transmission is done.

• Options: "Transmission completed" / "Want to review input contents"
• If "Want to review input contents" is selected, confirm location to review and return to applicable step

1. Record acceptance number — Read and record acceptance number from screen
2. Confirm reception notification — Confirm reception notification in message box
3. Consumption tax declaration — Proceed to Step 6.5 if consumption tax declaration is required. Proceed to Step 7 if not required

• Corrections after transmission require re-submission as an "amended return"
• ★★★ Transmission must always be done manually by the user — Agent must never automatically click the transmission button ★★★

Input and confirmation of consumption tax declaration contents are complete.

We strongly recommend saving the input data as a .data file before proceeding to digital signature and transmission.
Click the "Temporarily save input data" button at the top of the screen and download the file.

Please select the next operation.

• Options:
  • "Proceed to digital signature and transmission" → Proceed to 6.5-2
  • "Review input contents" → Confirm location to review and return to applicable step
  • "Stop here" → Follow interruption procedure in Interruption/Resumption Protocol and exit

Proceeding to consumption tax digital signature screen.
Perform digital signature with your My Number Card.

Please select "Signature completed" once signature is done.

• Options: "Signature completed" / "Problem occurred during signature"
• Do not perform any browser operations until user selects "Signature completed"

1. Read contents of confirmation page on browser
2. Report main items to user (Tax base amount, consumption tax amount, net tax amount, local consumption tax, total payment amount, etc.)
3. Report comparison results with shinkoku calculation results

Consumption tax pre-transmission confirmation page is displayed.
Please confirm the above contents.

If there are no issues, click the "Execute transmission" button on the screen
with your own operation.

Please select "Transmission completed" once transmission is done.

• Options: "Transmission completed" / "Want to review input contents"
• If "Want to review input contents" is selected, confirm location to review and return to applicable step

1. Record acceptance number — Read and record acceptance number from screen
2. Confirm reception notification — Confirm reception notification in message box
3. Proceed to Step 7 guide to save .data file

.data

Transmission is complete. The .data file after transmission includes information such as acceptance number.
We recommend re-downloading the .data file via "Save input data".

Please select "Downloaded" once download is complete.

• Options: "Downloaded" / "Skip"

• If you have a .data file, you can resume from the middle next time via "Create using saved data"
• Useful as a copy (can be referenced as previous year's data during next year's declaration)
• If amended return is required, input data can be restored from .data file

• Based on jQuery 3 + jQuery UI
• Page transitions are via form POST (

  document.forms[formName].submit()

  )
• Hashes

  #bsctrl

  (Financial Statement Corner) /

  #bbctrl

  (Income Tax Corner) are for page management

• <input type="button">

  is frequently used, and JS

  .click()

  operation is performed with

  id="input_xxx"

• doSubmitCSW0100(qrCodeReadingFlag, reportType, url)

  — Select authentication method

• doSubmitCMW0900(zeimokuType, year)

  — Select return form type (1=Income Tax, 2=Financial Statement, 3=Consumption Tax, 4=Gift Tax)

1. #otherTax

   — "Do you want to create other return forms?"

2. #end

   — "Are you sure you want to exit?"

• URL does not change
• DOM contents do not change (no transition to new screen)
• Button click appears to do nothing

1. If dialog possibility is detected, display the following using AskUserQuestion:

Button was clicked, but screen did not transition.
Is a pop-up (confirmation dialog) displayed in your browser?

If displayed, please tell us the dialog contents (including code number if any).

• Options: "Dialog is displayed" / "Dialog is not displayed"

1. If dialog is displayed:
   • Confirm dialog message content with user
   • Check if it corresponds to known codes (KS-W*, KS-E*, etc. in "Confirmation Dialogs" table above)
   • KS-W series (warning): Guide user to click "OK"
   • KS-E series (error): Guide correction according to error content
   • Unknown dialog: Ask user to share full message and determine handling
2. If dialog is not displayed:
   • Investigate possibility of network error or page loading
   • Try reloading page