nta_get_qa の仕様
INFO
houki-nta-mcp v0.27.1 の specs/current/nta_get_qa/spec.md から自動生成しました（仕様 ID 16 件・2026-10-12）。手で編集しないでください。再生成は node scripts/generate-reference.mjs specs です。
質疑応答事例を 1 件取得する
使いどころ・引数・実測の呼び出し例は、ツールのページにあります。
最後に仕様が変わったのは v0.24.0 の「国税庁サイトから取る経路（通信の失敗の code・タックスアンサーの URL と 8xxx 帯）と、事務運営指針の legal_status.note（段階 5）」（2026-10-03 承認）です。それまでの経緯は承認の履歴にあります。
利用者と得られる結果
この機能の利用者と、利用者が渡すもの・得られる結果を示します。
- MCP クライアント（Claude などの LLM、または CLI から呼ぶ人）。
topic・category・idを渡して、国税庁の質疑応答事例 1 件の照会要旨・回答要旨・関係法令通達を受け取る
入力
呼び出すときに渡す値です。
| 引数 | 必須 | 内容 |
|---|---|---|
topic | 必須 | 税目フォルダ。shotoku / gensen / joto / sozoku / hyoka / hojin / shohi / inshi / hotei のどれか |
category | 必須 | カテゴリ番号（章に当たる）。例: "02"。1 桁でもよい。1 桁か 2 桁の半角の数字（SPEC-NTA-GET-QA-013）。空文字・空白だけは不可（002）。全角の数字は半角に揃えてから読む（016） |
id | 必須 | 事例番号。例: "19"。1 桁でもよい。1 桁か 2 桁の半角の数字（SPEC-NTA-GET-QA-013）。空文字・空白だけは不可（002）。全角の数字は半角に揃えてから読む（016） |
format | 任意 | markdown（既定）または json |
扱わないこと
この機能が意図して扱わないことです。
- markdown の応答で
related_laws/related_tsutatsu/next_actionsを返すこと（json のときだけ。markdown は【関係法令通達】の節をページの表記のまま載せる） - 事例番号を題名やキーワードから探すこと（探すのは
nta_search_qa） - 関係法令通達に挙がった法令・通達の本文を返すこと（
next_actionsで案内するだけ） - 回答要旨が今の法令でも成り立つかを判定すること（
qa.basisDateは国税庁が書いた作成時点をそのまま返す）
処理の流れ
呼び出しを受けてから応答を返すまでに、何をどの順で確かめるかを示します。図の中の番号は「できること」の仕様 ID の末尾 3 桁です。
仕様項目
この機能の仕様項目を、仕様 ID ごとに並べています。見出しは仕様項目を 1 文で表したもので、条件・応答の細部・例は「詳細」を開くと読めます。仕様 ID はそれぞれ受入テストと対応していて、テストの無い ID があると各リポジトリの CI が止まります。
SPEC-NTA-GET-QA-001 対応していない税目は取りに行かない
詳細
topic が上の 9 税目のどれでもないときは、エラー INVALID_ARGUMENT を返す。hint に対応している税目の一覧を書く。DB も国税庁サイトも引かない。
SPEC-NTA-GET-QA-002 category と id が空文字・空白だけのときは取りに行かない
詳細
category / id が空文字のときは、inputSchema の minLength: 1 の検査（SPEC-NTA-COMMON-ERRORS-013）で止まり、INVALID_ARGUMENT（tool: "nta_get_qa"、detail.issues[].path はその引数名、message: "空文字は指定できません"）を返す。空白（半角スペース・全角スペース・タブ・改行）だけのときは、ツールの処理が DB と国税庁サイトを引く前に、SPEC-NTA-COMMON-ERRORS-014 の形の INVALID_ARGUMENT（error: "<引数名> が空です"、detail.issues: [{ path: "<引数名>", message: "空白だけは指定できません" }]、hint に税目の目次ページ（/law/shitsugi/{topic}/01.htm）でカテゴリ番号と事例番号を確かめるよう書く）を返す。
例: { topic: "shohi", category: "", id: "19" } は detail.issues が [{ path: "category", message: "空文字は指定できません" }]。{ topic: "shohi", category: "02", id: " " } は error: "id が空です"・detail.issues[0].path: "id"。どちらも code: "INVALID_ARGUMENT" で、DB も国税庁サイトも引かない。
SPEC-NTA-GET-QA-003 1 桁の category と id は 2 桁に揃えてから引く
詳細
category と id は、1 桁なら先頭に 0 を付けて 2 桁に揃える（"2" → "02"）。揃えた値で DB を引き、国税庁サイトに取りに行くときは https://www.nta.go.jp/law/shitsugi/{topic}/{category}/{id}.htm を取得する。
SPEC-NTA-GET-QA-004 ローカル DB にある事例は DB から返す
詳細
その事例がローカル DB にある（--bulk-download-qa または以前の取得で入った）ときは、国税庁サイトに取りに行かずに DB の内容を返す。json の応答の source は db。qa.fetchedAt は DB に入れたときの日時のまま（呼び出した時刻にしない）。
SPEC-NTA-GET-QA-005 DB に無い事例は国税庁サイトから取る
詳細
その事例が DB に無いときは、国税庁サイトの該当ページを取得して返す。json の応答の source は live。
SPEC-NTA-GET-QA-006 国税庁サイトから取った事例は DB に入り、次からは DB から返す
詳細
SPEC-NTA-GET-QA-005 で取得した事例は DB に入る。同じ事例をもう一度求められたときは国税庁サイトに取りに行かず、source が db の応答を返す。このときの応答は、国税庁サイトから取ったときと同じ構造である（qa.question / qa.answer の段落の配列と、そこから作る related_laws が残っている）。DB への書き込みに失敗しても、その呼び出しの応答は返す。
SPEC-NTA-GET-QA-007 markdown（既定）の応答
詳細
format を省くか markdown にしたとき、応答は次を含む文字列である。DB から返したときも国税庁サイトから取ったときも同じ形。
- 見出し
# <題名>と、> 税目: <topic> / カテゴリ: <category> / 事例番号: <id>の行 ## 【照会要旨】・## 【回答要旨】・## 【関係法令通達】の節（中身が無い節は出さない）- ページ下部の注記（作成時点と、一般的な回答である旨の断り書き）がある事例では、
## 【関係法令通達】の後ろに独立した## 注記（国税庁）の節。注記は## 【関係法令通達】の節には入れない 出典: <国税庁ページの URL>・取得: <取得日時>・取得元: <ローカル DB（bulk download で取り込んだもの）| 国税庁サイト（この呼び出しで取得）>- 質疑応答事例の位置付けの注（国税庁の参考解説資料で法的拘束力はなく、実務判断は通達・法令本文に基づく必要があること）
SPEC-NTA-GET-QA-008 json の応答
詳細
format を json にしたとき、応答は次のフィールドを持つ。値の無いフィールドは null にし、キーは無くさない。
| フィールド | 内容 |
|---|---|
qa.topic / qa.category / qa.id | 税目・カテゴリ番号・事例番号（2 桁に揃えたもの） |
qa.title | 題名 |
qa.question / qa.answer | 照会要旨・回答要旨の段落の配列 |
qa.relatedLaws | 【関係法令通達】の段落の配列（ページの表記のまま） |
qa.notice / qa.basisDate | ページ下部の注記と、その注記から読んだ作成時点の日付（YYYY-MM-DD）。注記が無い事例ではどちらも null。注記はあるが日付を読めないときは qa.basisDate だけ null |
qa.sourceUrl / qa.fetchedAt | 出典 URL と取得日時 |
index_status / orphaned_at / notice | SPEC-NTA-GET-QA-010。索引にある事例と、この呼び出しで国税庁サイトから取った事例では null |
source | db または live |
legal_status | binds_citizens: false / binds_courts: false / binds_tax_office: false と注 |
例: 注記の無い事例を format: "json" で取ると、qa.notice: null・qa.basisDate: null（v0.22.0 ではどちらのキーも無かった）。
SPEC-NTA-GET-QA-009 関係法令通達を法令と通達に分け、本文を読む案内を付ける
詳細
json の応答では、【関係法令通達】を読み取って次を付ける。読み取れたものが無ければそのフィールドは付けない。
related_laws: 法令の参照。要素はlaw_name・article・paragraph・item・raw（元の表記）related_tsutatsu: 通達の参照。要素はname・clause・rawnext_actions: 法令は houki-egov-mcp のget_lawを、通達はnta_get_tsutatsuを、読み取った引数付きで案内する。同じ案内は 1 回だけ入れる
例: shohi/02/19 の「消費税法第2条第1項第8号、消費税法基本通達5-1-1」からは、related_laws に { law_name: "消費税法", article: "2", paragraph: 1, item: 8 }、related_tsutatsu に { name: "消費税法基本通達", clause: "5-1-1" } が入り、next_actions はこの 2 つを読む案内の 2 件になる。
SPEC-NTA-GET-QA-010 国税庁の索引から消えた事例に印を付け、それ以外では印のキーを null にする
詳細
DB から返す事例（SPEC-NTA-GET-QA-004）が国税庁の索引から外れている（bulk download で外れたことを確認した日時が付いている）ときは、応答に印を付ける。
formatがjsonのとき:index_status: "removed_from_index"、orphaned_at（確認した日時。例:"2026-10-01T00:30:00Z"）、notice（索引から外れている旨と、過去の課税期間では意味を持つ場合があること、現在の取扱いは最新の通達で確かめること、出典 URL が 404 になることがあることの注記）を付けるformatを省くかmarkdownのとき:> 税目: … / カテゴリ: … / 事例番号: …の行の後に、> **索引の状態**: removed_from_index（<確認した日時> に確認）の行と、>で始まる注記の行を入れる- 索引にある事例と、この呼び出しで国税庁サイトから取った事例では、json の
index_status・orphaned_at・noticeをどれもnullにし（キーは無くならない）、markdown に「索引の状態」の行と注記を入れない
注記の文は nta_get_jimu_unei（SPEC-NTA-GET-JIMU-UNEI-004）と同じである。
例: 索引にある事例を DB から format: "json" で取ると、index_status: null・orphaned_at: null・notice: null（v0.22.0 ではどのキーも無かった）。
SPEC-NTA-GET-QA-011 条まで読めない法令や、基本通達 4 種以外の通達は next_actions に入れない
詳細
SPEC-NTA-GET-QA-009 の next_actions には、読み取った参照のうち次のものを入れない。入れないものも related_laws / related_tsutatsu には残す。
- 法令: 条（
article）まで読めなかったもの。法令名が「法」「令」「規則」「法律」のどれでも終わらないもの（例:日米租税条約）。法令名が「旧」で始まるか「改正前」を含むもの（例:旧所得税法） - 通達: 番号（
clause）まで読めなかったもの。消費税法基本通達・所得税基本通達・法人税基本通達・相続税法基本通達の 4 種以外の通達
通達の番号の末尾に (4) のような細目があるときは、next_actions の example.clause からは細目を外す（related_tsutatsu の clause は元のまま）。
例: 【関係法令通達】が「消費税法第2条第1項第8号、消費税法基本通達5-1-1(4)」「日米租税条約第3条」「旧所得税法第9条」の事例では、related_laws は 3 件だが、next_actions の法令の案内は 消費税法 の 1 件だけになる。通達の案内の example は { name: "消費税法基本通達", clause: "5-1-1" } で、related_tsutatsu の clause は 5-1-1(4) のまま。
SPEC-NTA-GET-QA-012 段落の構造を持たない DB の行は、国税庁サイトから取り直す
詳細
DB にその事例の行があっても、段落の構造（照会要旨・回答要旨・関係法令通達を分けたもの）を持たない行（v0.16.0 より前に DB に入れた行）や、構造の記録が読めない行は、DB から返さず、DB に無いとき（SPEC-NTA-GET-QA-005）と同じく国税庁サイトから取る。応答の source は live になり、取った事例は SPEC-NTA-GET-QA-006 のとおり DB に書き戻す。次の呼び出しからは DB から返す（source: "db"）。
SPEC-NTA-GET-QA-013 category と id は 1 桁か 2 桁の半角の数字で、それ以外は取りに行かずに INVALID_ARGUMENT を返す
詳細
category と id の形は、前後の空白を除いて、半角の数字 1 桁か 2 桁である（SPEC-NTA-COMMON-ERRORS-015）。それ以外（英字を含む、3 桁以上、記号を含む）のときは、DB と国税庁サイトを引く前に INVALID_ARGUMENT（tool: "nta_get_qa"、error: "<引数名> の形が受け付ける形ではありません: <渡した値>"、detail.issues: [{ path: "<引数名>", message: "1 桁か 2 桁の数字で指定してください" }]、hint に "02"・"19" のような例）を返す。形が正しければ SPEC-NTA-GET-QA-003 のとおり 2 桁に揃えて引く。
例: { topic: "shohi", category: "02", id: "19" } と { topic: "shohi", category: "2", id: "9" } は検査を通る。{ topic: "shohi", category: "1a", id: "19" } は detail.issues[0].path: "category"、{ topic: "shohi", category: "02", id: "190" } は detail.issues[0].path: "id" で、どちらも code: "INVALID_ARGUMENT"、DB も国税庁サイトも引かない（v0.21.3 では引いてから DOC_NOT_FOUND か SOURCE_API_ERROR になっていた）。
SPEC-NTA-GET-QA-014 国税庁サイトにページが無い（404・410・404 ページへの転送）ときは DOC_NOT_FOUND を返し、検索ツールを案内する
詳細
topic / category / id の事例が DB に無く国税庁サイトから取るとき、国税庁サイトが HTTP 404 か 410 を返した、または https://www.nta.go.jp/error/404.htm に転送したときは、エラー DOC_NOT_FOUND（retryable: false）を返す（SPEC-NTA-COMMON-ERRORS-016）。SOURCE_API_ERROR にはしない。
error: 渡した引数の値と、そのページが国税庁サイトに無いことhint: 番号を確かめる案内（nta_search_qa で探す）next_actions:{ action: "nta_search_qa", reason: "キーワード検索で正しい番号を探せます", example: { topic: <渡した topic>, keyword: "<探したい語>" } }の 1 件。retry_laterは入れないdetail.status: 国税庁サイトが返した HTTP ステータス（転送のときは 404）、detail.url: 取りに行った URLtool:nta_get_qa
例: 国税庁サイトが 404 を返す状態で { topic: "shohi", category: "99", id: "99" } を渡すと、code: "DOC_NOT_FOUND"、retryable: false、next_actions[0].action: "nta_search_qa"（v0.21.3 では SOURCE_API_ERROR・retryable: true・retry_later だった）。/error/404.htm への転送でも、410 でも同じ。
SPEC-NTA-GET-QA-015 国税庁サイトとの通信が失敗したときは、失敗の種類ごとの SOURCE_* を返す
詳細
国税庁サイトから取るとき（SPEC-NTA-GET-QA-005）に、要求がページが無い（SPEC-NTA-GET-QA-014）以外の形で失敗したときは、SPEC-NTA-COMMON-ERRORS-018 の表の code・retryable・next_actions・detail のエラーを返す。tool は nta_get_qa。
| 国税庁サイト | code | retryable | next_actions |
|---|---|---|---|
| HTTP 429 | SOURCE_RATE_LIMITED | true | retry_later |
| 30 秒以内に応答しない（取り直しても） | SOURCE_TIMEOUT | true | retry_later |
| HTTP 5xx（取り直しても） | SOURCE_API_ERROR | true | retry_later |
| HTTP 403・400 など（404・410・429 を除く 4xx） | SOURCE_API_ERROR | false | 付けない |
| 接続できない（取り直しても。SPEC-NTA-COMMON-ERRORS-019） | SOURCE_UNAVAILABLE | true | retry_later |
例: 国税庁サイトが 503 を返す状態で { topic: "shohi", category: "02", id: "19" } を渡すと、code: "SOURCE_API_ERROR"、retryable: true、detail.status: 503。403 を返すときは code: "SOURCE_API_ERROR"、retryable: false、next_actions 無し（v0.23.0 では retryable: true・retry_later）。429 なら SOURCE_RATE_LIMITED、接続できない（cause.code: "ENOTFOUND"）なら SOURCE_UNAVAILABLE・detail.cause: "ENOTFOUND"（v0.23.0 ではどちらも SOURCE_API_ERROR）。
SPEC-NTA-GET-QA-016 category と id は半角に揃えてから形を確かめる
詳細
category と id は、前後の空白を除いた値を houki-abbreviations の normalizeJpText の規則（全角英数字を半角に、ダッシュ類 － ‐ ‑ – — ― − を - に、全角チルダ ～ 〜 を ~ に、全角空白を半角空白にし、前後の空白を除く。罫線 ─ と長音 ー は変えない。大文字と小文字は区別する）で揃えてから、SPEC-NTA-GET-QA-013 の形の検査に進む（SPEC-NTA-SEARCH-RULES-019）。揃えた後の値で DB を引き、国税庁サイトの URL を組み立てる。
例: { topic: "shohi", category: "０２", id: "１９" } は { topic: "shohi", category: "02", id: "19" } と同じ応答（v0.21.3 では全角のまま DB を引き、国税庁サイトの /law/shitsugi/shohi/０２/１９.htm を取りに行っていた）。
実装する人に向けた情報
ここから下は、この機能を実装する人と、仕様の変更を追う人に向けた節です。使い方を知りたいだけなら、読まなくて構いません。
検討中のこと
仕様を書き起こしたときに見つかった項目のうち、扱いを Issue で検討しているものです。ここに挙げたことは、今後の版で変わることがあります。開くと、元の仕様書の記述をそのまま読めます。
仕様書の「未決」の節
初版起こしで見つけた、意図か不具合かを人が決める項目です。決まったら「できること」に ID を振るか、specs/changes/ の差分にします。
意図か不具合かの判断が要る項目は houki-nta-mcp の Issue に移し、ここには題と Issue の番号だけを残します。今の振る舞いのままでよくテストが無いだけの項目は、受入テストを書いてから「できること」に ID を振ります。
承認の履歴
この機能の仕様が、いつ、どの変更で承認されたかを新しい順に並べています。各リポジトリの npx spec-ids history nta_get_qa と同じ内容です。変更の名前から、変更の理由と前後の振る舞いを書いた文書（GitHub）を開けます。
承認の履歴（12 件）
| 承認日 | 版 | 変更 | 仕様 PR |
|---|---|---|---|
| 2026-10-03 | v0.24.0 | 国税庁サイトから取る経路（通信の失敗の code・タックスアンサーの URL と 8xxx 帯）と、事務運営指針の legal_status.note（段階 5） | #134 |
| 2026-10-03 | v0.23.0 | 値の無いフィールドを null にし、検索の結果に発出日と法令時点を揃えて返す（T4 応答の形） | #125 |
| 2026-10-01 | v0.22.0 | 全角・半角・ダッシュ類の揃え方を houki-abbreviations 0.7.0 に一本化する（T3） | #119 |
| 2026-10-01 | v0.22.0 | 「見つからない」と「取得元の失敗」の code を分ける（T2） | #118 |
| 2026-10-01 | v0.22.0 | 引数の検査を inputSchema に書き、丸めずに INVALID_ARGUMENT にする（T1） | #117 |
| 2026-09-27 | v0.21.1 | 索引から消えた文書の印に、取得系 4 ツールの仕様 ID を振り、検索系 4 ツールのテストを足す | #91 |
| 2026-09-27 | v0.21.1 | 取得系ツールと nta_inspect_pdf_meta の応答の形に仕様 ID を振る | #89 |
| 2026-09-27 | v0.21.1 | DB から返すか国税庁サイトから取るかの分かれ目に、仕様 ID とテストを足す | #88 |
| 2026-09-27 | v0.21.1 | 引数の検査と、国税庁のページの解析の失敗のエラーに仕様 ID を振る | #84 |
| 2026-09-26 | v0.21.1 | 「未決」のうち判断が要る 45 件を Issue に移す | #74 |
| 2026-09-26 | v0.21.1 | 全 14 ツールの spec.md に「処理の流れ」の節を足す | #63 |
| 2026-09-24 | — | 初版 | #52 |
関連ページ
このページの元になった文書と、あわせて読むページです。