이 서버가 열 수 있는 폴더와 제한값을 조회합니다.

모든 작업의 출발점입니다. 경로를 추측해서 다른 도구를 부르지 말고, 여기서 얻은 root 아래의 경로만 넘기세요. root 밖은 전부 거부됩니다.

Returns: AllowedRootsResponse: roots[](경로·존재여부), 여는 확장자 목록, 파일 크기 상한, 스캔 개수 상한, 그리고 이 제한들이 적힌 설정 파일 경로.

Examples: - 사용: "어떤 폴더를 분석할 수 있나요?" / 다른 도구가 PATH_OUTSIDE_ROOT로 거부했을 때 - 사용하지 않음: 이미 root를 알고 파일 목록이 필요할 때 → scan_folder

폴더 안의 대상 문서를 목록화합니다. 파일을 열지 않습니다.

stat 정보만 보므로 큰 폴더에서도 빠릅니다. 대신 스캔 PDF와 텍스트 PDF를 구분할 수 없습니다 — expected_grade가 B?인 파일은 inspect_document로 확정하세요.

개수는 코드가 셉니다. total_matched와 returned가 다르면 truncated가 True이고, 범위를 좁혀 다시 호출해야 합니다.

Args: folder: root 절대경로 또는 root 기준 상대경로. recursive: 하위 폴더 포함 여부. extensions: 확장자 필터.

Returns: ScanFolderResponse: entries[]와 확장자별·등급별 집계.

Examples: - 사용: "이 폴더에 뭐가 들어 있나요?" / 분석 대상을 고르기 전 - 사용하지 않음: 특정 파일의 페이지 수·제목 구조가 필요할 때 → inspect_document

본문 없이 구조와 확정 등급만 돌려줍니다.

read_document 전에 부르세요. 300페이지 PDF에서 "이게 어떻게 생긴 문서인지"를 알려고 본문 전체를 컨텍스트에 붓는 일을 막는 도구입니다.

scan_folder의 expected_grade는 확장자 추정값이라 pdf·svg가 B?로 남습니다. 이 도구가 파일을 열어서 확정합니다. 스캔 PDF와 텍스트 PDF가 여기서 갈립니다.

파일을 여는 비용은 read_document와 같습니다. 절약되는 것은 시간이 아니라 컨텍스트입니다.

Args: path: 분석할 파일.

Returns: InspectResponse: 확정 등급과 근거, 제목 트리, 블록 수, 본문 글자 수, 전체를 읽는 데 필요한 호출 횟수 추정, 이미지 판독이 필요한 블록 앵커, 형식별 메타.

Examples: - 사용: 큰 PDF를 읽기 전에 페이지 수와 목차를 확인할 때 - 사용: scan_folder가 'B?'를 돌려줬고 스캔 여부를 알아야 할 때 - 사용하지 않음: 본문 내용이 필요할 때 → read_document

문서 본문을 인용 앵커를 붙여 범위 지정으로 읽습니다.

형식이 달라도 인터페이스는 하나입니다. 모든 형식을 블록의 1차원 목록으로 평탄화하므로 start/end만 쓰면 됩니다. 블록 하나가 무엇인지는 응답의 unit이 알려 줍니다 (pdf=페이지, pptx=슬라이드 줄, docx=문단·표행).

등급이 C면 텍스트가 없다는 뜻입니다. 그때는 read_document_image로 넘어가세요 — 이 도구가 빈 본문을 돌려주는 것을 "내용이 없다"로 읽으면 안 됩니다.

요약할 때 앵커를 그대로 인용하세요. Phase 4의 check_summary_grounding이 그 앵커로 원문 대조를 합니다. 앵커 없는 문장은 근거 없는 문장으로 처리됩니다.

Args: path: 읽을 파일. start: 시작 블록 번호(1부터). end: 끝 블록 번호(포함). 생략하면 글자 수 상한까지.

Returns: ReadDocumentResponse: 확정 등급, 앵커 붙은 본문, 구조화 블록, 형식별 메타.

Examples: - 사용: "이 PDF 3~8페이지에 뭐가 있나요?" → start=3, end=8 - 사용하지 않음: 페이지 수·제목 구조만 필요할 때 → inspect_document - 사용하지 않음: 등급 C 파일 → read_document_image

텍스트가 없는 문서를 이미지로 받아 직접 판독합니다.

png는 원본을, pdf는 해당 페이지에 임베드된 이미지를 돌려줍니다. 스캔 PDF는 페이지 전체가 하나의 이미지이므로 이 방법으로 판독됩니다. 벡터로만 그려진 페이지는 꺼낼 수 없고, 그때는 오류가 사람이 할 일을 알려 줍니다.

이미지는 긴 변 1568px로 줄여서 넘어옵니다. 판독 정확도에는 영향이 없습니다.

판독한 내용은 원문 인용이 아닙니다. 요약에 쓸 때는 "(이미지 판독)"을 표기하세요. 텍스트 앵커와 같은 근거로 취급하면 안 됩니다.

Args: path: png 또는 pdf 경로. page: pdf의 페이지 번호.

Returns: list: 이미지 한 장과, 출처·크기·다음 단계를 적은 안내 문자열. (바이너리를 돌려주는 유일한 도구이므로 구조화 응답 규약에서 벗어납니다.)

Examples: - 사용: read_document가 등급 C를 돌려준 뒤 - 사용하지 않음: 등급 A·B 파일 → read_document로 텍스트를 읽는 게 정확합니다

초안을 쓰기 위한 재료를 한 번에 받습니다 — 템플릿 + 앵커 붙은 원문 + 목차.

read_document를 따로 부를 필요가 없습니다. 초안은 당신이 씁니다 — 이 도구는 형식과 원문을 주기만 합니다.

source_with_anchors에 있는 앵커만 인용하세요. 여기 없는 앵커를 쓰면 preview_save_report가 GR-02로 막습니다.

required_sections의 절을 빠뜨리면 저장이 막힙니다. ungrounded_sections의 절에는 앵커를 붙이지 않아도 됩니다.

Args: path: 분석할 파일. start: 시작 블록 번호. end: 끝 블록 번호(포함).

Returns: BuildPromptResponse: 템플릿·목차·앵커 붙은 원문·확정 등급·절 목록.

Examples: - 사용: "이 문서 분석해 줘" 를 받은 직후 - 사용하지 않음: 본문 일부만 다시 보고 싶을 때 → read_document - 사용하지 않음: 등급 C 문서 → read_document_image로 판독한 뒤 초안을 씁니다

초안의 각 문장이 원문 앵커에 근거하는지 대조합니다.

확인하는 것: 앵커를 인용했는가(GR-01) · 그 앵커가 있는가(GR-02) · 수치·날짜가 원문에 있는가(GR-03) · 직접 인용이 원문과 같은가(GR-04).

확인하지 못하는 것: 요약이 뜻을 제대로 옮겼는가 · 중요한 것을 빠뜨렸는가 · 인용한 앵커가 적절한가. GR-05는 어휘 겹침 힌트일 뿐이고 판단은 사람이 합니다. 응답의 not_verifiable이 이 한계를 명시합니다 — 통과했다는 것이 맞다는 뜻은 아닙니다.

원문을 다듬어 쓰는 것은 정상입니다. 대조는 앵커·수치·직접 인용만 봅니다.

Args: path: 원본 파일. draft: 초안 전문.

Returns: GroundingResponse: 규칙 위반 목록, 검사·면제 통계, 인용 범위(coverage).

Examples: - 사용: 초안을 쓴 직후, 저장 전 - 사용하지 않음: 저장 계획과 승인 토큰이 필요할 때 → preview_save_report

저장 게이트를 통과하는지 확인하고 승인 토큰을 발급합니다. 쓰지 않습니다.

구조(ST-)와 근거(GR-)를 모두 보고, 오류가 하나도 없을 때만 approval_token이 발급됩니다.

토큰은 이 초안 내용에 묶여 있습니다. 초안을 한 글자라도 고치면 토큰이 달라지므로 다시 미리보기해야 합니다. 깨끗한 초안으로 미리보기하고 다른 초안을 저장하는 경로를 막기 위한 것입니다.

will_overwrite가 True면 기존 산출물을 덮어씁니다. previous_hash와 line_delta로 무엇이 바뀌는지 확인하고 사람에게 알린 뒤 진행하세요.

Args: path: 원본 파일. draft: 초안 전문.

Returns: PreviewResponse: 게이트 결과, 저장 위치, 덮어쓰기 여부, 승인 토큰.

Examples: - 사용: 근거 대조를 통과한 뒤, 저장 직전 - 사용하지 않음: 근거만 보고 싶을 때 → check_summary_grounding

승인된 초안을 output_root에 저장합니다. 이 서버의 유일한 쓰기 도구입니다.

사용자가 명시적으로 승인한 뒤에만 부르세요. 승인은 사람만 할 수 있는 단계입니다. 미리보기가 READY라는 것은 "저장해도 된다"가 아니라 "게이트를 통과했다"는 뜻입니다.

게이트를 전부 다시 확인합니다 — 구조 · 근거 · 토큰 · 저장 위치. 미리보기가 통과했다는 말을 믿지 않습니다. 오류가 남아 있으면 DRAFT_NOT_CLEAN, 초안이 바뀌었으면 APPROVAL_TOKEN_MISMATCH로 거부합니다.

기존 산출물이 있으면 덮어씁니다. 덮어쓴 사실과 이전 내용의 해시는 감사 기록에 append됩니다 — 기존 기록을 고치거나 지우지 않습니다.

Args: path: 원본 파일. draft: 초안 전문. 미리보기 때와 같아야 합니다. approval_token: 미리보기가 발급한 토큰.

Returns: SaveResponse: 저장 위치, 덮어쓰기 여부, 감사 기록 항목.

Examples: - 사용: 사람이 "저장해"라고 말한 뒤 - 사용하지 않음: 미리보기가 BLOCKED인 상태 — 저장되지 않습니다 - 사용하지 않음: 사람의 승인 없이 흐름을 이어가려 할 때