How the strict Parameter in agent.run() Controls Ungrounded Tool Calls in Needle

When strict=True (the default), agent.run() validates that all tool arguments are grounded in the source context and rejects ungrounded calls with an error object; when strict=False, the agent ignores grounding validation and executes tools with potentially fabricated arguments.

The strict parameter in agent.run() acts as a safety gate for the Needle agent's tool-calling loop. It determines whether the library enforces grounding validation—verifying that function arguments reference actual information from the source text—before allowing tool execution. Understanding this parameter is essential for controlling the trade-off between safety and flexibility when building LLM-powered applications with the cactus-compute/needle library.

What the strict Parameter Controls

The strict parameter governs the grounding check performed on every tool call generated by the LLM. According to the source code in needle/__init__.py, the agent uses the helper function _ungrounded_paths() to extract any arguments that lack source validation from the model's response.

The Grounding Validation Logic

Inside the main execution loop (lines 83‑101), the code evaluates each function call:

ungrounded = _ungrounded_paths(response)
for call in calls:
    name = str(call.get("name"))
    fabricated = sorted(ungrounded.get(name, ()))
    if strict and fabricated:
        results.append({"error": "ungrounded " + ", ".join(fabricated)})
        continue
    …

This logic compares the strict boolean against the presence of ungrounded fields. When both conditions are true, the tool call is aborted and an error is recorded.

Behavior When strict=True (Default)

When you set strict=True—the default behavior—the agent enforces strict grounding requirements. If the LLM attempts to invoke a tool with arguments that cannot be verified against the source context, the call is replaced with an error object and the tool function never executes.

The error message explicitly lists the offending fields. For example, if the model fabricates a date argument, the result contains:

{"error": "ungrounded date"}

This prevents the agent from acting on hallucinated or out-of-context information, improving reliability in retrieval-augmented generation workflows.

Behavior When strict=False

Setting strict=False disables the grounding guard. In this mode, the agent ignores the validation results from _ungrounded_paths() and proceeds to invoke the tool regardless of whether arguments are grounded in the source text.

The tool receives the arguments as-is, and any errors will only surface from the tool's internal logic or external API failures. Use this mode when you want the LLM to use its parametric knowledge or when working with tools that don't require source-text verification.

Code Examples: Comparing strict Modes

The following examples demonstrate the practical difference between modes using the Needle library.

Example 1: Default Strict Mode Rejecting Ungrounded Arguments

from needle import Needle

needle = Needle()

# strict=True is the default

response = needle.run(
    query="Schedule a meeting on March 15, 2025",
    max_steps=2,
    strict=True,
)

# Results contain an error instead of tool output:

# [{"error": "ungrounded date"}]

In this case, because the date could not be grounded in the provided source material, the agent returns an error object rather than calling the calendar tool.

Example 2: Non-Strict Mode Allowing Tool Execution

response = needle.run(
    query="Schedule a meeting on March 15, 2025",
    max_steps=2,
    strict=False,  # Permit ungrounded arguments

)

# The calendar tool receives the date string and executes,

# even though the date wasn't verified against source text.

Here, the tool executes with the potentially fabricated date, delegating validation to downstream logic.

Implementation Reference Points

The grounding validation system is implemented across several key files in the repository:

• needle/__init__.py (lines 83‑101): Contains the run() method's main loop where the strict flag is evaluated against ungrounded paths.
• needle/__init__.py (lines 37‑44): Defines _ungrounded_paths(), which parses the LLM's validation output to identify fabricated fields.
• needle/agent/tools.py: Handles tool registration; the strict parameter determines whether registered functions receive filtered or unfiltered arguments.

Summary

• The strict parameter in agent.run() toggles grounding validation for tool arguments.
• When strict=True (default), ungrounded arguments trigger an error object and the tool is not executed.
• When strict=False, the agent skips validation and calls tools with potentially ungrounded arguments.
• The check is implemented in needle/__init__.py using the _ungrounded_paths() helper to identify fabricated fields.

Frequently Asked Questions

What is the default value of the strict parameter in agent.run()?

The default value is True. Unless explicitly set to False, the agent will enforce grounding validation and reject any tool calls containing arguments that cannot be verified against the source context.

Does strict=False improve performance by skipping validation?

No, the validation via _ungrounded_paths() still occurs internally to identify ungrounded fields. However, with strict=False, the agent simply ignores these results and proceeds with tool execution, so the performance difference is negligible. The primary impact is on safety and correctness, not speed.

Can I set strict individually for different tools in the same run?

No, the strict parameter applies globally to all tool calls within a single agent.run() invocation. To apply different validation rules to different tools, you would need to run separate agent.run() calls with different strict configurations or handle filtering within the tool implementations themselves.

What happens if a tool has multiple arguments and only some are ungrounded?

When strict=True, if any argument is ungrounded, the entire tool call is rejected. The error message lists all ungrounded fields (e.g., "ungrounded date, location"), and the tool receives no execution opportunity. The agent treats partial grounding as a failure condition.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}