Sql Agent Laravel Package

title: Agent Tools description: Detailed reference for all tools available to the LLM agent during query execution. sidebar: order: 5

The agent uses a set of tools during its agentic loop to introspect the database, search knowledge, execute SQL, and persist learnings. Each tool is registered with the LLM as a callable function with a JSON Schema describing its parameters.

This page documents every tool, its parameters, the JSON sent to the LLM, and what the tool returns.

How Tools Are Sent to the LLM

Tools are serialized into the format expected by each LLM provider. The package handles this automatically via ToolFormatter.

OpenAI / Ollama Format

{
  "type": "function",
  "function": {
    "name": "tool_name",
    "description": "What the tool does.",
    "parameters": {
      "type": "object",
      "properties": { ... },
      "required": [ ... ]
    }
  }
}

Anthropic Format

{
  "name": "tool_name",
  "description": "What the tool does.",
  "input_schema": {
    "type": "object",
    "properties": { ... },
    "required": [ ... ]
  }
}

The parameters (OpenAI) and input_schema (Anthropic) objects are identical — only the wrapper differs.

run_sql

Execute a SQL query against the database. This is the primary tool the agent uses to answer questions.

Description sent to LLM:

Execute a SQL query against the database. Only SELECT and WITH statements are allowed. Returns query results as JSON.

Parameters

{
  "type": "object",
  "properties": {
    "sql": {
      "type": "string",
      "description": "The SQL query to execute. Must be a SELECT or WITH statement."
    }
  },
  "required": ["sql"]
}

Return Value

{
  "rows": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ],
  "row_count": 2,
  "total_rows": 2,
  "truncated": false
}

Safety

• Only SELECT and WITH statements are allowed (configurable via sql.allowed_statements).
• Forbidden keywords (DROP, DELETE, UPDATE, INSERT, ALTER, CREATE, TRUNCATE, etc.) are rejected even inside subqueries.
• Multiple statements separated by ; are blocked.
• Results are capped at sql.max_rows (default: 1000).
• On error, a SqlErrorOccurred event is dispatched for auto-learning.

Example Tool Call

{
  "sql": "SELECT COUNT(*) as total FROM orders WHERE status = 'delivered'"
}

introspect_schema

Inspect the database schema. The agent uses this to discover tables, columns, types, foreign keys, and sample data before writing SQL.

Description sent to LLM:

Get detailed schema information about database tables. Can inspect a specific table or list all available tables.

Parameters

{
  "type": "object",
  "properties": {
    "table_name": {
      "type": "string",
      "description": "Optional: The name of a specific table to inspect. If not provided, lists all tables."
    },
    "include_sample_data": {
      "type": "boolean",
      "description": "Whether to include sample data from the table (up to 3 rows). This data is for understanding the schema only - never use it directly in responses to the user.",
      "default": false
    }
  }
}

Return Value

When listing all tables (no table_name provided):

{
  "tables": ["users", "orders", "products"],
  "count": 3
}

When inspecting a specific table:

{
  "table": "orders",
  "description": "Table comment if set in the database",
  "columns": [
    {
      "name": "id",
      "type": "bigint",
      "nullable": false,
      "primary_key": true,
      "foreign_key": false,
      "references": null,
      "default": null,
      "description": null
    },
    {
      "name": "customer_id",
      "type": "bigint",
      "nullable": false,
      "primary_key": false,
      "foreign_key": true,
      "references": "customers.id",
      "default": null,
      "description": null
    }
  ],
  "relationships": [
    {
      "type": "belongsTo",
      "related_table": "customers",
      "foreign_key": "customer_id",
      "local_key": "id"
    }
  ],
  "sample_data": [
    {"id": 1, "customer_id": 42, "status": "delivered", "total_amount": 9999}
  ]
}

Example Tool Call

{
  "table_name": "orders",
  "include_sample_data": true
}

search_knowledge

Search the knowledge base for relevant query patterns and learnings. The agent calls this before writing SQL to find proven patterns and avoid known pitfalls.

Description sent to LLM:

Search the knowledge base for relevant query patterns and learnings. Use this to find similar queries, understand business logic, or discover past learnings about the database.

Parameters

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query to find relevant knowledge."
    },
    "type": {
      "type": "string",
      "description": "Filter results: 'all' (default), 'patterns' (saved query patterns), or 'learnings' (discovered fixes/gotchas).",
      "enum": ["all", "patterns", "learnings"]
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results to return.",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": ["query"]
}

Return Value

{
  "query_patterns": [
    {
      "name": "monthly_revenue",
      "question": "Calculate total revenue by month",
      "sql": "SELECT DATE_FORMAT(created_at, '%Y-%m') as month, SUM(total_amount) / 100 as revenue FROM orders WHERE status != 'cancelled' GROUP BY month ORDER BY month DESC",
      "summary": "Monthly revenue from non-cancelled orders",
      "tables_used": ["orders"],
      "relevance_score": 8.5
    }
  ],
  "learnings": [
    {
      "title": "orders.total_amount is in cents",
      "description": "Always divide total_amount by 100 when displaying dollar amounts.",
      "category": "data_quality",
      "sql": null,
      "relevance_score": 7.2
    }
  ],
  "total_found": 2
}

Example Tool Call

{
  "query": "monthly revenue calculation",
  "type": "patterns",
  "limit": 5
}

save_learning

Save a new learning to the knowledge base. The agent uses this when it discovers something important — typically after recovering from a SQL error or when a user provides a correction.

Description sent to LLM:

Save a new learning to the knowledge base. Use this when you discover something important about the database schema, business logic, or query patterns that would be useful for future queries.

:::note This tool is only available when sql-agent.learning.enabled is true (the default). :::

Parameters

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "A short, descriptive title for the learning (max 100 characters)."
    },
    "description": {
      "type": "string",
      "description": "A detailed description of what was learned and why it matters."
    },
    "category": {
      "type": "string",
      "description": "The category of this learning.",
      "enum": ["type_error", "schema_fix", "query_pattern", "data_quality", "business_logic"]
    },
    "sql": {
      "type": "string",
      "description": "Optional: The SQL query related to this learning."
    }
  },
  "required": ["title", "description", "category"]
}

Categories

Return Value

{
  "success": true,
  "message": "Learning saved successfully.",
  "learning_id": 12,
  "title": "users.status is VARCHAR not INT",
  "category": "type_error"
}

Example Tool Call

{
  "title": "orders.total_amount is in cents",
  "description": "The total_amount column stores values in cents, not dollars. Always divide by 100 when displaying monetary values.",
  "category": "data_quality",
  "sql": "SELECT total_amount / 100 as amount_dollars FROM orders"
}

save_validated_query

Save a validated query pattern after successfully answering a question. This builds the knowledge base organically — future similar questions can reference proven SQL.

Description sent to LLM:

Save a validated query pattern to the knowledge base. Use this when you have successfully executed a SQL query that correctly answers a user question. This helps future queries by providing proven patterns.

:::note This tool is only available when sql-agent.learning.enabled is true (the default). Saved queries appear alongside patterns from the Knowledge Base in search_knowledge results. :::

Parameters

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "A short, descriptive name for the query pattern (max 100 characters)."
    },
    "question": {
      "type": "string",
      "description": "The natural language question this query answers."
    },
    "sql": {
      "type": "string",
      "description": "The validated SQL query that correctly answers the question."
    },
    "summary": {
      "type": "string",
      "description": "A brief summary of what the query does and what data it returns."
    },
    "tables_used": {
      "type": "array",
      "description": "List of table names used in the query.",
      "items": {
        "type": "string"
      }
    },
    "data_quality_notes": {
      "type": "string",
      "description": "Optional: Notes about data quality issues, edge cases, or important considerations for this query."
    }
  },
  "required": ["name", "question", "sql", "summary", "tables_used"]
}

Return Value

{
  "success": true,
  "message": "Query pattern saved successfully.",
  "pattern_id": 7,
  "name": "monthly_active_users",
  "tables_used": ["users", "logins"]
}

Duplicate Detection

If a query pattern with the same question already exists, the tool returns an error instead of creating a duplicate. This prevents the knowledge base from accumulating redundant patterns.

Example Tool Call

{
  "name": "monthly_active_users",
  "question": "How many active users were there last month?",
  "sql": "SELECT COUNT(DISTINCT user_id) as active_users FROM logins WHERE created_at >= DATE_SUB(CURDATE(), INTERVAL 1 MONTH)",
  "summary": "Count of unique users who logged in during the last calendar month",
  "tables_used": ["logins"],
  "data_quality_notes": "Only counts users with at least one login event"
}

Tool Availability

Not all tools are available in every configuration:

When learning is disabled (SQL_AGENT_LEARNING_ENABLED=false), the save_learning and save_validated_query tools are not registered with the LLM, and the related instructions are removed from the system prompt.

In addition to the built-in tools above, you can register your own tools via the agent.tools config option. See the Custom Tools guide for details.