search-files-content-trim

search_files Content Trim — Token-Efficient Default

Audit Finding (2026-05-31)

{{AGENT_NAME}}의 search_files tool은 757자짜리 line을 500자 (ripgrep MAX_CONTENT cap)까지 매번 그대로 LLM context에 push했음. 단일 검색 결과 한 match에 500자 × 50 matches = 25,000 chars/검색. 99.2%의 검색 call은 path:line만 필요하고, full content는 LLM이 read_file()로 follow-up할 일 — 첫 search response의 full content는 낭비.

원인: ripgrep의 MAX_CONTENT=500이 1차 cap. search_tool은 그 이상 truncate 안 함. LLM은 매번 500 chars/line을 받음.

Fix (shipped 2026-05-31)

~/.{{AGENT_NAME_LOWER}}/source/{{AGENT_NAME_LOWER}}-agent/tools/file_tools.py 의 search_tool에 2개 파라미터 추가:

param	type	default	의미
include_content	bool	False	True면 full content, False면 preview로 truncate
preview_chars	int	100	False일 때 매치당 보존할 글자 수. 0이면 content 완전 drop (path:line만)

적용 위치 (총 4개):

1. SEARCH_FILES_SCHEMA — input schema에 2 properties 추가
2. search_tool signature — 2 파라미터 + docstring에 audit 결과 명시
3. search_tool body — redact_sensitive_text 직후 preview truncate 로직 (preview_chars=0 → "", > preview_chars → [:preview_chars] + "...")
4. _handle_search_files handler — args 2개 pass-through

Effect (verified)

시나리오	Before	After (default)	절약
757자 line 1 match	500 chars	103 chars (100+3)	79%
50 matches × 500 chars	25,000 chars	5,150 chars	79%
preview_chars=0 (path:line만)	500 chars	0 chars	100%
include_content=True (회귀 없음)	500 chars	500 chars	0% (의도)

When To Use

• default (no flag): LLM이 path:line만 필요하고 read_file()로 follow-up할 때. 대부분의 search 호출이 여기에 해당.
• preview_chars=0: "이 file들이 존재하는지만 알면 됨" 케이스. 50개 file의 path:line만 받고 다음 단계로 넘어감.
• include_content=True: LLM이 full line을 보고 결정해야 할 때 (e.g. multi-line regex match, raw text/JSON structure 파악).

Pattern: Token-Efficient Tool Default

이 패턴은 다른 tool에도 동일 적용 가능:

1. Audit current behavior: 한 tool call이 평균 몇 char를 LLM context에 push하는지 측정
2. Default = cheapest sane option: full content 필요 케이스만 opt-in (include_*=True)
3. Tunable: preview_chars 같은 numeric param으로 user가 명시적으로 trade-off 조절
4. Schema에 명시: LLM이 schema description 읽고 알아서 적절히 선택하도록 guide