On this page
Learning objectives
- Design tool descriptions and schemas that reduce ambiguity
- Validate permissions and arguments outside the model
- Return tool results in a form the agent can reason about
Prerequisites
LLM APIs and structured outputs · One safe test API
Answer first
Canonical definition
Tool calling lets a model propose a named operation with structured arguments; application code remains responsible for authorization, execution, error handling, and audit records.
Operating context
Why it matters
Tools connect model reasoning to real systems, which is also where data leakage and unintended side effects become possible.
A small, well-described capability surface is easier to select correctly and secure than a generic execute-anything tool.
Method
Step by step
- 01
Make tools narrow
Create capabilities around user intent such as fetch_order_status rather than exposing raw database or shell access.
- 02
Validate context
Check user identity, tenant, permission, argument shape, rate limit, and policy before execution.
- 03
Classify side effects
Mark tools read-only, reversible, externally visible, or irreversible and require approval accordingly.
- 04
Return useful observations
Provide concise structured results, stable error codes, and references the agent can cite or use in the next step.
Hands-on lab
Build a read-only account tool
Give a model one typed function that retrieves an authorized account record and returns a constrained result.
Deliverable
A tool schema, authorization layer, test doubles, audit record, and five adversarial argument tests.
What breaks
Common failure modes
- F1Trusting model-generated arguments as authorization
- F2Exposing a generic HTTP, SQL, or shell tool without containment
- F3Returning huge raw payloads that overflow context and hide errors
Beyond the demo
Production notes
- Use least privilege, short-lived credentials, per-tool rate limits, and explicit egress rules.
- Record who initiated the run, which tool was requested, validated arguments, result code, and approval decision.
Further reading
Sources
Related Tenten resources