When AI executes an API operation through Toolcog, everything stays in its right place. Parameters can’t leak into each other. Credentials can’t escape their scope. The LLM can’t reach operations outside a contained set.
The term “hygienic” comes from programming language theory—hygienic macro systems prevent names from accidentally escaping their scope. Toolcog applies the same principle to API execution. But the colloquial meaning works too: it’s clean.
AI can only execute operations from its catalog. It cannot:
When AI calls call_api, it provides an operation name. That name must match an indexed operation. There’s no mechanism to escape this constraint—no path traversal, no URL injection, no “just make a request to this endpoint.”
This is a feature, not a limitation. Constraining the interface is what makes it safe to give AI access to hundreds of thousands of operations.
Every parameter flows through its proper channel:
| Parameter Type | Where It Goes | How It’s Encoded |
|---|---|---|
| Path | URL template | RFC 6570 expansion |
| Query | Query string | Per OpenAPI style |
| Header | HTTP headers | Per scheme definition |
| Cookie | Cookie header | Per scheme definition |
| Body | Request body | Per content-type |
This isn’t policy—it’s architecture. The execution engine builds a request template from the OpenAPI spec with separate slots for each parameter location. AI’s arguments are organized by location: path, query, header, cookie, body. Each argument type expands only into its designated slot.
A path parameter cannot become a header because the data structures don’t allow it. A body field cannot become a query parameter because there’s no code path that would make it happen. The isolation is structural.
URL construction uses RFC 6570 URI template expansion, not string concatenation. Path parameters like ../admin/reset don’t traverse anywhere—they’re percent-encoded as literal path segments. The template expansion algorithm handles encoding; user input never touches string construction.
Before execution, every parameter is validated against its original JSON Schema—not the synthesized TypeScript types AI sees, but the full schema from the OpenAPI spec.
Toolcog implements every keyword of every major JSON Schema dialect (Draft 2020-12, Draft 07, Draft 04, OAS 3.0, OAS 3.1). Validation is exact, per spec.
This catches:
additionalProperties: false)When validation fails, AI receives precise feedback: what field, what constraint, what value. This enables self-correction. AI doesn’t have to guess what went wrong—the system tells it exactly.
Credentials are bound to specific security schemes, and only apply to operations that explicitly declare that scheme. This operates at the operation level, not the API level.
When the execution engine processes an operation, it extracts security requirements from the spec—which schemes are needed, what scopes they require. Credentials are then resolved from your vault and applied according to the scheme definition. API keys go where the scheme says (header, query, or cookie). OAuth tokens become Bearer headers. HTTP Basic credentials get base64-encoded.
The LLM has no influence over this process. It doesn’t choose which credentials to use. It doesn’t specify where they go. The OpenAPI security scheme controls everything. AI provides the operation name and parameters; credential resolution and application happen entirely outside AI’s view.
Even within the same API, credentials won’t apply to operations that don’t declare the matching scheme. An API might use different auth for admin endpoints versus user endpoints—admin credentials only flow to operations that declare the admin scheme.
Catalogs can restrict this further with overrides. You can scope credentials to specific operations: give an agent admin access, but only for one endpoint. Or configure multiple credential sets for the same API—read-only credentials for most operations, write credentials for a specific few—with precise control over which operations can use which.
The execution flow:
Each step is deterministic and spec-driven. The OpenAPI spec controls encoding. The security scheme controls authentication. AI provides values; the system handles everything else.
This is where tools as data pays off. Because the spec is data interpreted at runtime—not compiled code—the execution engine can enforce these properties uniformly for any API. The same structural guarantees apply whether AI is calling Stripe, GitHub, or your internal services.
AI receives structured feedback:
Validation failed for parameter 'body.amount': Expected: integer Received: "fifty" Path: body.amountAI can examine the error and retry with corrected values.
When credentials are missing or expired:
Operation requires authentication: stripe_oauthAuthorization URL: https://toolcog.com/connect?...AI presents the link. You authorize. AI retries.
Non-auth errors (400, 404, 500) pass through with full response bodies. AI sees what the API returned and can adjust its approach.
Letting AI execute arbitrary code connected to the open internet is risky. As a result, it’s generally not done—or it’s done with heavy sandboxing that limits usefulness.
Hygienic execution inverts this. By constraining the interface—contained operations, validated parameters, scoped credentials—the system becomes safe enough to trust with broad access. The constraint enables the capability.
The security properties aren’t assertions we make about careful code. They’re structural guarantees from the architecture. Parameters can’t leak because the data structures separate them. Credentials can’t escape because the resolution process is decoupled from AI input. Operations can’t be fabricated because execution requires a spec to interpret.
It’s also more reliable. There are more ways to get code wrong than right. Toolcog makes it easy for AI to get API calls right: synthesized interfaces show what’s needed, validation catches mistakes, and precise error messages enable correction.