tools.write_python_tool module
Create new Python tool files in the tools/ directory.
This tool writes a new .py file into the tools/ directory and handles all downstream registration automatically:
Syntax validation – parses the code with AST before writing.
File creation – writes the .py file (optionally overwriting).
Markdown docs – generates a Markdown doc from the source and indexes it into the
stargazer_docsRAG store so it is immediately searchable. Also creates an RST stub for the next full Sphinx rebuild.Registry reload – hot-reloads the tool registry so the new tool is callable in the same conversation.
Classifier embeddings – regenerates vector embeddings so the tool can be auto-selected by future prompts.
Requires the UNSANDBOXED_EXEC privilege.
What the LLM actually sees at tool-selection time
The OpenAI function-calling API sends exactly three fields per tool:
TOOL_NAME→function.nameTOOL_DESCRIPTION→function.description← the ONLY prose the LLM reads when deciding whether to call a toolTOOL_PARAMETERS→function.parameters
Module docstrings and run() docstrings are NOT sent to the LLM
directly. They are auto-extracted into Markdown docs and indexed into
the stargazer_docs RAG store, where the LLM can search them later
with rag_search.
Documentation best practices
TOOL_DESCRIPTION must be self-contained and comprehensive. It is the ONLY text the LLM sees at tool-selection time. Write it so that any future instance of Stargazer can understand the tool’s purpose, constraints, and usage in any context.
Function docstrings feed the auto-generated Markdown docs in the
stargazer_docsRAG store. Document every public function, parameter, and edge case for deeper reference.