Designing Safe AI Agent Tools: Names, Inputs and Side Effects

By Numan ·

A design checklist for narrow agent tools with validated arguments, clear results and controlled side effects.

Designing Safe AI Agent Tools: Names, Inputs and Side Effects

A tool definition is a contract between an agent and your application. Vague names and broad permissions make mistakes harder to spot. OpenAI's function-calling documentation (https://developers.openai.com/api/docs/guides/function-calling) recommends clear names and parameter descriptions; OWASP (https://genai.owasp.org/llmrisk/llm01-prompt-injection/) recommends least privilege and approval for high-risk actions.

Name the actual operation

Prefer create_draft(title, body) to manage_content(action, data). The first names a bounded effect. A read tool such as list_recent_posts(limit) should not publish, delete, or modify a counter unexpectedly. A description should state both what the tool does and what it does not do when that distinction affects a decision.

Constrain the arguments

Use types and limits that reflect the service's rules: maximum title length, allowed status values, and an authenticated user scope. Validate on the server even if the model produced a schema-conformant call. Schema validation catches shape errors; authorization catches who may act on which target.

Make side effects reviewable

For actions that send, publish, spend, or delete, show the proposed target and exact change to a human before execution. Keep an identifier for the request so a retry can be recognized. Return a result that includes the created object's ID or the reason for refusal.

Test ambiguous calls

Try a missing target, a mismatched account, an oversized body, and a duplicate request. Also put hostile instructions into a tool response and confirm they cannot grant new permission. A model may still misunderstand the tool; the backend must enforce the boundary.

The goal is a small catalog whose operations a reviewer can explain without guessing. Our MCP primitive guide (https://ubits.tech/learning/p/mcp-tools-vs-resources-vs-prompts) shows where tools sit beside resources and prompts.