Skip to main content
Glama

run_datalog

Run Datalog logic queries over a codebase graph to detect transitive calls, imports, dependencies, circular dependencies, hubs, orphans, and layer bypasses using preloaded predicates.

Instructions

Run a logic query over the codebase graph. Standard library predicates are pre-loaded (do not redefine them):

  • calls_transitive(X, Y) : X transitively calls Y

  • imports_transitive(X, Y) : X transitively imports Y

  • depends_transitive(X, Y) : X transitively depends on Y

  • same_community(X, Y) : X and Y are in the same Louvain cluster

  • is_hub(X) : X has > 15 connections

  • is_orphan(X) : X has no incoming/outgoing edges

  • circular_dependency(X, Y) : X and Y call each other

  • bypasses_layer(X, Y, Z) : X depends on Z, bypassing intermediary Y Base EDB relations: node, calls, imports, contains, inherits, implements, degree, edge. Supports user rules (:-), goals (?-), facts, and negation (not). Budget-bounded (max 10,000 steps).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "run_datalog"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesDatalog program text. Supports goals (?-), user rules (:-), facts, and negation (not). Standard library predicates are pre-loaded.
formatNoOutput format: 'text' (default, Markdown) or 'json' (datalog.v1 machine-readable report with per-query rows, variables, and step metadata).
step_budgetNoMaximum solver steps before the query is bounded (default 1000, clamped to 100 through 10000).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.26.2
    • addedInput schema / properties / format
      Added value: +{
      +  "description": "Output format: 'text' (default, Markdown) or 'json' (datalog.v1 machine-readable report with per-query rows, variables, and step metadata).",
      +  "type": "string"
      +}
  2. Changed2 schema fields changedv0.23.0
    • addedInput schema / properties / query / description
      Added value: +"Datalog program text. Supports goals (?-), user rules (:-), facts, and negation (not). Standard library predicates are pre-loaded."
    • addedInput schema / properties / step_budget / description
      Added value: +"Maximum solver steps before the query is bounded (default 1000, clamped to 100 through 10000)."
  3. First observedv0.1.0

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does reasonably well: it declares the pre-loaded environment, the EDB relation vocabulary, supported program constructs (rules, goals, facts, negation), and that execution is budget-bounded. Gaps remain: it never states that the operation is read-only / side-effect free, and 'max 10,000 steps' sits uneasily beside the schema's default of 1000, which could mislead an agent into thinking it always runs to 10,000.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded single sentence establishes the operation, then a reference list of predicates and relations, which is the densest-value content here. Every bullet arguably earns its place as reference material. Slightly list-heavy, but well ordered and free of filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description does not describe result shape (though the format parameter mentions datalog.v1 rows and variables). For a read query with three fully-documented parameters, the predicate/relation inventory is the decisive missing-otherwise context and it is present. A note on read-only semantics and failure modes would close the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description reinforces the query parameter by enumerating the predicate vocabulary an agent needs to author valid Datalog, which is real added value. It says nothing about the format or step_budget parameters, and its budget statement conflicts subtly with the schema's default/clamp semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Run a logic query over the codebase graph', and immediately narrows it to Datalog with pre-loaded standard-library predicates. An agent knows exactly what class of operation this is. It does not, however, distinguish itself from siblings such as query_graph or trace_path, so the reader must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The predicate catalogue implicitly tells the agent this tool is for transitive/community/hub-style graph analysis, which is genuine usage signal. But there is no explicit 'use this instead of query_graph when...' routing, no stated prerequisites, and no note on what happens if predicates are redefined despite the 'do not redefine them' warning.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.