Safe tool request
{
"tool": "get_service_status",
"arguments": {"service": "nginx"}
}
request → schema validation → policy → tool → structured result- The application mediates execution.
- Unknown tools and disallowed service names are rejected.
Agentic AI Engineering · Module 03 of 16
Giving Agents Tools
A model can talk about a server, but it cannot inspect that server unless the application gives it a capability. A tool is that capability—and it should be narrow, validated and controlled.
Engineering focus: Tool contracts, validation and least privilege
In plain English
What problem are we solving?
A model can talk about a server, but it cannot inspect that server unless the application gives it a capability. A tool is that capability—and it should be narrow, validated and controlled.
Framework names come later. First understand what the application is doing and where its control boundaries belong.
Running case · Operations Investigator
Across the course, imagine an assistant that investigates operational problems using narrow tools. The design progressively adds plans, specialist agents, approvals, reliability controls and MCP while keeping model output separate from execution authority.
Learning objectives
By the end of this module, you should be able to:
- Explain why tools extend an LLM beyond text generation.
- Design narrow read-only tool contracts with explicit inputs and outputs.
- Separate model intent from validated and authorized execution.
A tool is a contract, not just a function
A useful tool definition includes a name, purpose, input schema, validation rules, side-effect classification and structured result. Production tools also need authorization, timeout and audit behaviour.
Start narrow and read-only
A tool such as get_disk_usage() exposes one understandable capability. A generic run_any_shell_command(command) exposes an enormous attack and failure surface. Least privilege applies to agents too.
Model intent is not authority
The model may request get_service_status("nginx"), but application code decides whether the tool exists, whether the argument is valid and whether the caller is allowed to use it. A system prompt is not an authorization system.
Structured results reduce ambiguity
Returning fields such as service, status and evidence is easier to validate and trace than returning an unstructured blob. Structured contracts also make evaluation easier.
Worked examples
Bad first tool
def run_any_shell_command(command):
os.system(command)- The interface is too broad for a beginner agent.
- The model should not receive unrestricted shell authority.
Try it · core lab · account-free
Use narrow, safe read-only tools
Goal: Execute allowed tools and observe validation rejecting an unsupported request.
Before you start
- Python 3 only. The service-status path is a safe fixture and executes no shell command.
Run the tool lab
python3 public/labs/agentic-ai/03_safe_tools.pyInspect the allowed-tool registry
Notice that only named tools can execute.
Observe the rejection
The unsupported service must raise a validation error instead of being passed through.
Verify
- Hostname and disk tools return structured results.
- An unsupported service is rejected.
Expected outcome
- No arbitrary shell command is executed.
- The policy boundary is visible in code.
Break / fix · diagnose
- If the unsupported service succeeds, check the allowlist before the tool executes.
- If arguments fail unexpectedly, inspect type and required-field validation.
Production view
Safe agent platforms expose purpose-built tools with least privilege, schema validation, authorization and observable results rather than unrestricted command execution.
Avoid these traps
Common mistakes
- Giving the model a generic shell or SQL tool when a narrow operation would suffice.
- Treating tool descriptions as security policy.
- Skipping validation because the model usually produces the right JSON.
Knowledge check
Explain the control decision, not just the vocabulary.
Open every answer only after committing to your own answer. Opening all four answers records knowledge-check activity in My Learning.
1Which tool is the safest beginner design?
get_disk_usage() — A narrow read-only capability minimizes unintended side effects.
2The model requests get_service_status('unknown-service'). What should happen first?
Validate the argument against the tool contract/policy — Tool inputs must be validated before execution.
3Does a prompt saying 'never do anything unsafe' replace authorization?
No — Instructions influence behavior; authorization constrains capability.
4Why return structured tool results?
To make validation and downstream interpretation more reliable — Structured results are easier to validate, inspect and reason over.
My Learning
Record your progress for this module.
Progress is saved in this browser immediately. When you sign in to My Learning, it can also sync across devices.
Attempt the core lab and knowledge checks before marking the module complete.