Safe tool library

What you'll build

Step-by-step build

1. 1

   Define the tool interface

   Design one interface every tool implements: a name, an input schema, required scopes, and a run function. A uniform shape lets the library enforce the same guardrails on every tool. Nail this contract before writing any actual tool.

2. 2

   Enforce input validation

   Make the library validate every call against the tool's Zod schema before the run function is even reached. Treat model output as untrusted input, because a model can hallucinate or be manipulated into malformed requests. A call that fails validation must be rejected, never coerced.

3. 3

   Add authentication

   Require each call to carry a signed token identifying the caller, and reject calls without a valid one. Verify the signature before doing any work. Knowing who is calling is the prerequisite for every other control.

4. 4

   Add permission scopes

   Attach required scopes to each tool and check the caller's token grants them before running. This is how you give one agent read-only tools and another a broader set. Scopes are what let you bound blast radius per agent.

5. 5

   Add rate limits

   Use Redis counters to cap how often a tool can be called per caller and per window. Reject calls over the limit with a clear message. Rate limits stop a runaway agent from hammering a system or burning a quota.

6. 6

   Add an audit log

   Record every call with the caller, tool, arguments, decision, and outcome. An audit trail is what lets you answer what an agent did after the fact. Make sure denied calls are logged too, not only successful ones.

7. 7

   Add dry-run mode

   Support a mode where a tool reports what it would do without performing side effects. This lets you preview an agent's plan safely before granting it live access. Dry-run is the safety valve between building a tool and trusting it.

8. 8

   Prove the guardrails with tests

   Write tests that a bad input is rejected, an unauthorized caller is blocked, an out-of-scope tool is denied, and a rate limit trips. Tests are the proof the guardrails hold under the cases that matter. Package and publish the library once they pass.

Done when

• ✓A malformed argument is rejected before the tool runs
• ✓A caller without the required scope is denied
• ✓A caller over the rate limit is blocked with a clear reason
• ✓Every call, allowed or denied, appears in the audit log
• ✓Dry-run reports the intended action without causing any side effect

Ship it

Ship this as an npm package rather than a hosted app, with a README documenting the interface, scopes, and how to wrap a new tool. Use a free Redis tier such as Upstash for the rate-limit counters. Include a worked example agent that imports the library and shows a denied call and an allowed one.

What it proves: Shows you can make agent tools safe for real systems with validation, auth, scopes, and rate limits, one of the most valued production agent skills.

Paste this into Cursor, Claude, or ChatGPT and build it step by step.

You are my senior AI engineer pair. Help me build "Safe tool library" step by step. An agent is an LLM that calls tools; a tool is a function it can run. The key mindset is that model output is untrusted input, so every tool call must pass guardrails before it runs. A scope is a named permission a caller must hold to use a tool.

Stack: TypeScript as an importable library, Zod for strict input validation, Redis (free Upstash tier) for rate limits, signed JWT tokens carrying caller identity and scopes, and Vitest for tests. Publish to npm.

Requirements:
1. Define one tool interface: name, input schema, required scopes, run function.
2. Validate every call against its schema and reject malformed input.
3. Authenticate callers with signed tokens and enforce permission scopes.
4. Rate-limit per tool and per caller with Redis, and audit-log every call, allowed or denied.
5. Provide a dry-run mode that previews actions without side effects.

Work in this order: tool interface, then validation, then auth, then scopes, then rate limits, then the audit log, then dry-run, then guardrail tests. Give me commands and code for each step and STOP after each so I can test. Do not write the whole library at once.