text-find

name	text-find
description	Find a substring or pattern in a text document. Returns position with surrounding context. Deterministic — use this instead of asking the LLM to find substrings.
args	{"source":"required string — text to search (a `$stepN` binding or a literal)","pattern":"required string — substring or regex pattern to find","context_lines":"optional int (default 1) — lines of surrounding context per match"}

text-find

Locate patterns or substrings in text and return all matches with context.

Behavior

• Case-sensitive by default.
• Supports standard Python regex syntax in pattern.
• Returns every match (not just the first), with line/character position and the surrounding lines.
• Returns an empty result if no matches — not an error.

When to use vs assess / process_text

• text-find — exact substring or regex match. Deterministic. No LLM cost.
• assess — natural-language predicate (semantic match). LLM-backed.
• process_text — open-ended transformation with an instruction.

If you want "does this contain the literal string X?" → text-find. If you want "does this contain mention of X?" (paraphrases count) → assess.

Examples

{"thought": "find every TODO in the document", "tool": "text-find", "source": "$step1", "pattern": "TODO"}

{"thought": "locate error lines mentioning a timeout", "tool": "text-find", "source": "$step1", "pattern": "ERROR.*timeout", "context_lines": 3}