Tool Ecosystem and Naming Conventions

Relevant source files

• Lovable/Agent Tools.json

This document provides comprehensive documentation of Lovable's tool ecosystem, focusing on the systematic naming conventions and organizational structure. Lovable employs a prefix-based naming system that categorizes tools by their primary domain or service integration. This page covers tool discovery, naming patterns, and the complete catalog of available capabilities.

For information about Lovable's file editing strategies and line-replace operations, see 4.3.2. For details on specific integrations like image generation and security scanning, see 4.3.4 and 4.3.5.

Naming Convention Architecture

Lovable implements a domain-prefixed naming convention where tools are categorized by their functional area or external service integration. This systematic approach enables developers to quickly identify tool capabilities and locate related functionality.

Prefix-Based Organization Pattern

Sources: Lovable/Agent Tools.json1-436

Tool Category Distribution

Prefix	Domain	Tool Count	Primary Purpose
lov-*	Core Operations	14	File operations, search, dependencies, console/network access
secrets--*	Secrets Management	2	Encrypted secret storage and retrieval
supabase--*	Supabase Integration	2	Documentation search and retrieval
imagegen--*	Image Generation	2	AI-powered image creation and editing
websearch--*	Web Search	1	Real-time web information retrieval
analytics--*	Analytics	1	Project usage metrics and statistics
stripe--*	Stripe Payments	1	Payment integration setup
security--*	Security	3	Supabase backend security scanning
document--*	Document Processing	1	Multi-format document parsing

Sources: Lovable/Agent Tools.json1-436

Core File Operations (lov-* Tools)

The lov-* prefix encompasses Lovable's foundational file manipulation, search, and project management capabilities. These tools form the primary interface for code editing and repository management.

File Read/Write Operations

Sources: Lovable/Agent Tools.json40-229

lov-view: File Content Reading

The lov-view tool reads file contents with optional line range specification. Default behavior displays the first 500 lines when no range is specified.

Parameters:

• file_path (required): Relative path from project root (e.g., "src/App.tsx")
• lines (optional): Line ranges in format "1-800, 1001-1500"

Usage Guidelines:

• Do NOT use if file contents already provided in context
• Do NOT specify line ranges for files ≤500 lines (rely on default)
• Only use line ranges for large files requiring specific sections
• Execute multiple lov-view calls in parallel for efficiency

Sources: Lovable/Agent Tools.json144-159

lov-line-replace: Primary Editing Tool

The lov-line-replace tool is the PREFERRED method for editing existing files, using explicit line numbers for precise modifications. This tool validates that the search content matches the file at specified line ranges before applying replacements.

Parameters:

• file_path (required): Path to file being modified
• search (required): Content to find (use ellipsis ... for large sections)
• first_replaced_line (required): First line number (1-indexed)
• last_replaced_line (required): Last line number (1-indexed)
• replace (required): New content to substitute

Ellipsis Usage Pattern: For sections longer than ~6 lines, use ellipsis notation to reduce specification overhead:

1. Include first 2-3 lines of target section
2. Add ... on its own line
3. Include last 2-3 lines of target section
4. Focus on uniqueness for accurate matching

Critical Rules:

• Line numbers are 1-indexed (first line = 1)
• Use original line numbers when making parallel edits to same file
• Search content must exactly match file content (excluding line numbers)
• Prefix and suffix around ellipsis must be exact matches

Sources: Lovable/Agent Tools.json57-89

lov-write: Full File Overwrite

The lov-write tool overwrites entire files and is designated as a FALLBACK mechanism. Primary use cases are creating new files or recovering from lov-line-replace failures.

Parameters:

• file_path (required): Relative path from project root
• content (required): Complete file content

Minimization Requirements:

• Use lov-line-replace for most changes instead of rewriting
• Maximize use of // ... keep existing code comments for unchanged sections
• Any unchanged block >5 lines MUST use keep-existing-code comment
• Comment must contain exact string "... keep existing code"

Parallel Execution: When creating multiple files, invoke lov-write simultaneously for all files rather than sequentially.

Sources: Lovable/Agent Tools.json40-56

Search and Discovery Tools

lov-search-files: Regex-Based Code Search

Special Character Handling: Use \\ to escape special characters in regex patterns (e.g., "useEffect\\(" to search for useEffect( literally).

Sources: Lovable/Agent Tools.json15-39

Dependency Management

The dependency management tools interact with npm package registry to add or remove project dependencies. Version specifications can be included in the package parameter (e.g., "lodash@latest", "[email protected]").

Sources: Lovable/Agent Tools.json2-199

External Resource Retrieval

lov-download-to-repo: URL-Based File Download

Downloads files from URLs directly into the repository. Primary use cases include image assets, external resources, and file migration.

Parameters:

• source_url (required): URL of file to download
• target_path (required): Destination path in repository (use public folder unless specified)

Important Constraint: Do NOT use this tool for user-uploaded images in chat. Follow instructions provided with user images instead.

Sources: Lovable/Agent Tools.json90-108

lov-fetch-website: Web Content Scraping

Fetches website content and temporarily saves it in tmp://fetched-websites/ directory. Returns file paths and content preview.

Parameters:

• url (required): Website URL to fetch
• formats (optional): Comma-separated list: 'markdown', 'html', 'screenshot' (default: 'markdown')

Sources: Lovable/Agent Tools.json109-126

Runtime Diagnostics

lov-read-console-logs: Console Log Capture

Reads console logs captured at the moment of user request. Provides optional search filtering.

Key Constraints:

• Logs are static snapshot from request time
• Do NOT use multiple times (same logs returned)
• Cannot verify fixes by re-reading logs (no updates during code writing)

Parameters:

• search (required): Filter query (empty string returns all logs)

Sources: Lovable/Agent Tools.json161-173

lov-read-network-requests: Network Activity Capture

Reads network requests with optional search filtering. Similar constraints to console logs apply.

Parameters:

• search (required): Filter query (empty string returns all requests)

Sources: Lovable/Agent Tools.json174-186

External Service Integration Tools

Lovable's external service integrations use double-dash (--) separators in their naming convention, distinguishing them from core operations. This section documents the specialized tools for third-party services.

Secrets Management (secrets--*)

Critical Security Guidelines:

• This is the ONLY way to collect secrets from users
• Never ask users to provide secret values directly
• All secrets automatically available as environment variables in backend code
• Do NOT add secrets through any other mechanism

Parameters:

• secret_name (required): Environment variable name (e.g., "STRIPE_API_KEY")

Sources: Lovable/Agent Tools.json230-255

Supabase Documentation Integration (supabase--*)

The Supabase tools provide access to official documentation via the Content API, enabling comprehensive implementation guidance retrieval.

supabase--docs-search: Documentation Search

Searches Supabase documentation with ranked results including title, slug, URL, and content snippets.

When to Use:

• Finding auth, database, storage, or edge function documentation
• Searching for code examples or implementation guides

Search Strategy:

• Use specific terms: "row level security", "auth policies", "storage buckets"
• Try different keyword combinations if initial search fails
• Follow up with supabase--docs-get using returned slug

Parameters:

• query (required): Search query string
• max_results (optional): Maximum results (default: 5, max: 10)

Sources: Lovable/Agent Tools.json256-272

supabase--docs-get: Full Documentation Retrieval

Fetches complete Supabase documentation pages by slug, returning structured content with full markdown, headings outline, and metadata.

Slug Format:

• Pattern: "category/subcategory/page-name"
• Examples: "auth/row-level-security", "storage/uploads"

Output Includes:

• Complete markdown content with code snippets
• Structured headings outline
• Page metadata

Sources: Lovable/Agent Tools.json273-285

Image Generation (imagegen--*)

Lovable integrates AI-powered image generation using Flux models, with tools for both creation and editing.

imagegen--generate_image: Text-to-Image Generation

Generates images from text prompts and saves to specified file paths.

Model Selection:

• flux.schnell (default): Fast, high-quality, recommended for small images (<1000px)
• flux.dev: Higher quality, slower, use for large images (hero images, fullscreen banners)

Parameters:

• prompt (required): Text description of desired image
• target_path (required): Save location (prefer src/assets/ folder)
• width (optional): Width in pixels (512-1920, multiples of 32)
• height (optional): Height in pixels (512-1920, multiples of 32)
• model (optional): "flux.schnell" or "flux.dev"

Prompting Tips:

• Mention aspect ratio in prompt for better results
• Use "Ultra high resolution" suffix to maximize quality
• Specify image type (e.g., "hero image", "banner")

Import Requirement: Generated images MUST be imported as ES6 modules:

Sources: Lovable/Agent Tools.json299-327

imagegen--edit_image: Image Editing and Merging

Edits existing images or merges multiple images based on text prompts.

Capabilities:

• Single image: AI-powered edits ("make it rainy", "change to sunset lighting")
• Multiple images: Merge/combine operations ("blend these two landscapes", "create a collage")

Use Case: Excellent for object/character consistency across scenes. When users request tweaks to existing images, prefer this tool over generating new images.

Parameters:

• image_paths (required): Array of image file paths
• prompt (required): Edit/merge instruction
• target_path (required): Output file location

Sources: Lovable/Agent Tools.json328-351

Web Search (websearch--*)

websearch--web_search: Real-Time Information Retrieval

Performs web searches returning relevant results with text content, optional links, and image links.

Search Operators:

• Domain filtering: "site:docs.anthropic.com API documentation"
• Multiple domains: "site:docs.anthropic.com site:github.com"
• Exact phrases: '"gpt5" model name' (include "gpt5" exactly)
• Exclude words: "jaguar speed -car" (exclude "car")

Category Filtering (exact strings required):

• "news"
• "linkedin profile"
• "pdf"
• "github"
• "personal site"
• "financial report"

Parameters:

• query (required): Search query string
• numResults (optional): Number of results (default: 5)
• links (optional): Number of links per result
• imageLinks (optional): Number of image links per result
• category (optional): Result category filter

When to Use:

• Current information not in training data
• Technical documentation from specific sources
• Real (non-AI-generated) images
• Information about specific entities (people, companies, events)

Sources: Lovable/Agent Tools.json352-380

Analytics (analytics--*)

analytics--read_project_analytics: Production Metrics

Reads analytics for production builds between specified dates with configurable granularity.

Parameters:

• startdate (required): RFC3339 format or YYYY-MM-DD
• enddate (required): RFC3339 format or YYYY-MM-DD
• granularity (required): "hourly" or "daily"

When to Use:

• User requests app usage statistics
• Production app improvement analysis

Sources: Lovable/Agent Tools.json381-398

Stripe Integration (stripe--*)

stripe--enable_stripe: Payment Setup

Enables Stripe integration by prompting user for Stripe secret key.

Parameters: None required (empty object)

Sources: Lovable/Agent Tools.json399-406

Security Scanning (security--*)

The security tools provide comprehensive analysis of Supabase backend configurations, detecting exposed data, missing RLS policies, and misconfigurations.

security--run_security_scan

Initiates comprehensive security analysis of Supabase backend.

Parameters: None required (empty object)

Sources: Lovable/Agent Tools.json407-414

security--get_security_scan_results

Fetches security scan results. Set force=true to retrieve results even when scan is still running.

Parameters:

• force (required): Boolean flag for forced retrieval

Sources: Lovable/Agent Tools.json415-426

security--get_table_schema

Retrieves database table schema information and security analysis prompt for Supabase database.

Parameters: None required (empty object)

Sources: Lovable/Agent Tools.json427-434

Document Processing (document--*)

document--parse_document: Multi-Format Document Parser

Parses and extracts content from documents (first 50 pages), supporting PDFs, Word docs, PowerPoint, Excel, MP3, and other formats. Preserves document structure, extracts tables and images, and performs OCR on embedded images.

Parameters:

• file_path (required): Path to document file

Sources: Lovable/Agent Tools.json286-298

Tool Discovery and Schema Access

All tool definitions in Lovable are stored in structured JSON format at Lovable/Agent Tools.json providing programmatic access to tool schemas, parameter requirements, and usage documentation.

Tool Definition Structure

Each tool entry follows this schema:

Sources: Lovable/Agent Tools.json1-436

Complete Tool Inventory

Comprehensive Tool Catalog by Category

Category	Tools	Count
File Operations	lov-view, lov-write, lov-line-replace, lov-delete, lov-rename, lov-copy	6
Search & Discovery	lov-search-files	1
Dependency Management	lov-add-dependency, lov-remove-dependency	2
External Resources	lov-download-to-repo, lov-fetch-website	2
Runtime Diagnostics	lov-read-console-logs, lov-read-network-requests	2
Secrets Management	secrets--add_secret, secrets--update_secret	2
Supabase Integration	supabase--docs-search, supabase--docs-get	2
Image Generation	imagegen--generate_image, imagegen--edit_image	2
Web Search	websearch--web_search	1
Analytics	analytics--read_project_analytics	1
Stripe Payments	stripe--enable_stripe	1
Security Scanning	security--run_security_scan, security--get_security_scan_results, security--get_table_schema	3
Document Processing	document--parse_document	1
TOTAL		26

Sources: Lovable/Agent Tools.json1-436