Skip to main content
Glama

ingest_directory_to_graph

Build a knowledge graph from local files by chunking matching documents, extracting entities and relations across a distributed grid, and writing graph outputs while skipping secret files.

Instructions

Build a knowledge graph from local files: chunk every file under directory_path that matches glob_pattern (~chunk_size characters per chunk, with overlap), extract entities/relations on the grid, then write /<job_id>/output_graph.jsonl and the resolved graph.json. Returns their paths, top entities/relations, timings, and every skipped file with the reason. Only reads inside the allowed roots; refuses secret files (.env, keys, credentials). Relative paths are resolved against the first allowed root. With wait=false returns after dispatch; graph.json appears when the job finishes.

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": {
      "directory_path": "<directory_path>"
    },
    "name": "ingest_directory_to_graph"
  }
}

Input Schema

NameRequiredDescriptionDefault
waitNo
chunk_sizeNo
glob_patternNo**/*.md
required_tierNo
directory_pathYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations only declare readOnly=false, openWorld=true, destructive=false; the description adds substantial context beyond that — exact output artifacts (<out>/<job_id>/output_graph.jsonl and graph.json), skip reporting with reasons, secret-file refusal, root restriction, and the wait=false async/non-final semantics. The one gap is that it never states that a job runs on grid infrastructure with associated latency or resource consumption, though 'on the grid' hints at it.

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-loads purpose then layers behavior, and nearly every sentence carries unique information (chunking, outputs, skip reasons, security, path resolution, async). The opening sentence is long and packs several concepts, but no sentence is redundant.

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?

For a multi-stage ingestion job this is close to complete: inputs, output artifacts, return payload, security constraints, and async behavior are all covered, and an output schema exists so return values need not be detailed further. The unexplained required_tier parameter is the main 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 0%, so the description carries the burden, and it does explain directory_path (files under it), glob_pattern (matching), chunk_size (~characters per chunk with overlap), and wait (returns after dispatch vs. waiting for graph.json). required_tier, however, is never mentioned, leaving one of five parameters with no stated meaning.

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

Purpose5/5

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

States a specific verb and resource — 'Build a knowledge graph from local files' — and immediately details the pipeline (chunk → extract entities/relations on the grid → write output_graph.jsonl and graph.json). This is unmistakably distinct from query_local_graph or grid_status, so an agent can route correctly without opening the schema.

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?

Usage is implied rather than stated: it establishes that it only reads inside allowed roots, refuses secret files, and resolves relative paths against the first allowed root, which tells the agent what inputs are acceptable. However, it never contrasts itself with siblings such as dispatch_mapreduce_text or states when not to use it, so routing guidance is only partial.

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