Tools Reference

The Clarity MCP server exposes 11 tools organized into four categories. Here's every tool, its parameters, and when to use it.

Project & File Tools

list_projects

List all projects in your Clarity workspace. Returns metadata for every non-trashed project.

When to use: Start here to get the project_id needed by other tools.

list_files

List all files in a project. Returns names, types, paths, and the main-file flag.

When to use: Explore a project's file tree and get file_id values for other tools.

read_file

Read the full content of a file.

When to use: Before editing, diagnosing errors, or answering questions about a file.

write_file

Update the content of an existing file. Replaces the entire file.

create_file

Create a new file in a project. Use this when the user needs a new .tex, .typ, .bib, .sty, or any other file.

Safety features:

• Validates file names (no slashes, max 255 chars)
• Prevents duplicate names in the same folder
• Verifies parent folder exists

When to use: When the user asks to create a new chapter, bibliography, style file, figure file, or any new document.

delete_file

Delete a file from a project. This action is permanent.

Safety features:

• Cannot delete the main entry file — set a different main file first
• Cannot delete non-empty folders — delete contents first
• Verifies ownership before deleting

Compilation & Debugging

compile

Compile a project and return the result. Automatically detects LaTeX vs Typst and the correct engine.

Returns: status, PDF flag, diagnostics (errors with line numbers), and truncated compile log.

debug_compile

Compile and return a structured error analysis. Use this when compilation fails — it provides categorized errors, suggested fixes, and a step-by-step debugging workflow.

What it does beyond `compile`:

• Categorizes errors (undefined commands, missing files, syntax issues)
• Suggests specific fix actions for each error type
• Extracts the most relevant log lines
• Returns a debugging workflow: read → fix → write → compile again

When to use: When a previous compile failed, or when the user says "my document won't compile."

Typst Documentation

typst_docs_search

Search the built-in Typst documentation library. Covers Typst language features and the Touying presentation framework.

Returns: matched docs with titles, paths, relevance scores, and content snippets.

When to use: When writing or editing Typst files and you need to look up functions, syntax, or patterns.

typst_docs_read

Read a specific Typst documentation file. Use after typst_docs_search to get the full content.

When to use: When a search result looks relevant and you need the complete documentation.

TikZ Illustration

tikz_illustrate

Generate professional TikZ illustrations. Creates a new file and provides structured guidance for producing high-quality diagrams.

Capabilities:

• Flowcharts and process diagrams
• Neural network architectures
• Mathematical plots (via pgfplots)
• Commutative diagrams (via tikz-cd)
• Feynman diagrams (via tikz-feynman)
• Tree structures and hierarchies
• General scientific illustrations

When to use: When the user asks for a diagram, figure, illustration, or visual in their LaTeX document.

Typical workflows

Edit and compile

1. 1list_projects → find the project
2. 2list_files → explore the structure
3. 3read_file → read the target file
4. 4write_file → apply changes
5. 5compile → verify it compiles

Create a new file

1. 1list_projects → find the project
2. 2create_file → create the new file with initial content
3. 3read_file on the main file → add an \input{} or #include reference
4. 4write_file → update the main file
5. 5compile → verify everything works

Debug a failing build

1. 1debug_compile → get structured error analysis
2. 2read_file → read the file with errors
3. 3write_file → fix the issues
4. 4compile → confirm the fix

Write Typst with confidence

1. 1typst_docs_search → look up the syntax you need
2. 2typst_docs_read → read the full documentation
3. 3write_file or create_file → write correct Typst code
4. 4compile → verify it renders properly