Pensieve Docs

Agent Tools Reference

referencetoolsagents

Agent Tools Reference

Pensieve agents use a set of shared tools to interact with the filesystem, the web, and project data. Tools are injected into each agent based on what that agent needs. This reference describes all 7 tools.

Tool Assignment Matrix

Tool Topic Refiner Researcher Outliner Drafter Content Reviewer Fact Checker Style Reviewer Reviser Polisher Consistency Checker
web_search ✅ ✅
fetch_url ✅ ✅
search_topics ✅ ✅
read_project_file ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
write_project_file ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
text_stats ✅
list_projects ✅

Runs a keyword query against the configured search provider (Tavily, SerpAPI, or Brave) and returns a list of results.

Parameters

Parameter Type Required Description
query string Yes The search query

Returns

A list of result objects, each containing:

Field Type Description
title string Page title
url string Page URL
snippet string Short excerpt from the page

On error or when rate-limited, returns an error string.

Notes

  • Only available when a search provider is configured in the global config and SEARCH_API_KEY is set.
  • Rate-limited to 1 request per second to avoid hammering the provider.
  • Results are not fetched — use fetch_url to retrieve full page content.
  • max_results_per_query in the global config limits the number of results returned.

Agents

Used by: Researcher, Fact Checker

fetch_url

Fetches a web page and returns its content as plain text.

Parameters

Parameter Type Required Description
url string Yes The URL to fetch
mode string No text (default) — plain text extracted from HTML; raw — raw HTML; summary — LLM-generated summary

Returns

A string containing the page content. On error (network failure, robots.txt disallowed, timeout), returns an error string.

Notes

  • Respects robots.txt — if crawling is disallowed, the tool returns an error string rather than fetching the page.
  • Uses trafilatura to extract clean text from HTML in text mode.
  • summary mode makes an additional LLM call to summarize the page content — use sparingly.
  • Default timeout is 10 seconds. Default max content length is 50,000 characters.

Agents

Used by: Researcher, Fact Checker

search_topics

Searches your topic memory library for files relevant to a given query.

Parameters

Parameter Type Required Description
query string Yes The topic or concept to search for

Returns

A list of matching topic file entries, each containing:

Field Type Description
slug string The topic file slug (e.g., langchain-agents)
title string The topic title from its frontmatter
snippet string A short excerpt from the topic file

Returns an empty list if no matches are found.

Notes

  • Searches across all topic files in workspaces/<workspace>/topics/.
  • Matching is semantic — the agent can use natural language queries.
  • Results are ranked by relevance.
  • Use this tool to surface prior knowledge before researching a topic from scratch.

Agents

Used by: Topic Refiner, Researcher

read_project_file

Reads a file from the current project directory.

Parameters

Parameter Type Required Description
filename string Yes Name of the file to read (e.g., draft_v1.md, outline.md)

Returns

A string containing the file contents. Returns an error string if the file does not exist.

Notes

  • Scoped to the current project directory (workspaces/<workspace>/projects/<project>/).
  • Cannot read files outside the project directory.
  • All agents have this tool — they use it to read artifacts produced by earlier stages.

Common Files Read by Agents

File Read by
topic_brief.md Outliner, Drafter, Content Reviewer, Fact Checker, Style Reviewer, Reviser, Consistency Checker
research_notes.md Outliner, Drafter, Fact Checker, Reviser
outline.md Drafter
draft_v1.md Content Reviewer, Fact Checker, Style Reviewer, Reviser, Polisher (fallback)
draft_v2.md Polisher
content_review.md Reviser
fact_check.md Reviser
style_review.md Reviser
final.md Consistency Checker

Agents

Used by: All agents

write_project_file

Writes a file to the current project directory.

Parameters

Parameter Type Required Description
filename string Yes Name of the file to write (e.g., draft_v1.md)
content string Yes The content to write

Returns

A success confirmation string. Returns an error string if the write fails.

Notes

  • Scoped to the current project directory — cannot write outside it.
  • Overwrites the file if it already exists.
  • Each agent writes its designated output file at the end of its work. This is how pipeline artifacts are produced.

Agents

Used by: All agents

text_stats

Returns word count, character count, and estimated reading time for a string.

Parameters

Parameter Type Required Description
text string Yes The text to analyze

Returns

An object containing:

Field Type Description
word_count integer Number of words
char_count integer Number of characters (including spaces)
reading_time_minutes float Estimated reading time at 200 words per minute

Notes

  • Used by the Polisher to check whether the article meets length targets before finalizing.
  • Can also be called by other agents for informational purposes, but only the Polisher has it in its default tool set.

Agents

Used by: Polisher

list_projects

Lists all projects in the current workspace.

Parameters

None.

Returns

A list of project entries, each containing:

Field Type Description
id string The project directory name (slug)
brief string The topic brief from brief.md
status string Current pipeline status: pending, running, paused, complete, error

Notes

  • Scoped to the current workspace — the Consistency Checker uses this to find prior articles and check for cross-article consistency.
  • Projects without a brief.md or status.json are omitted.

Agents

Used by: Consistency Checker

See Also