Integration · Guide
Write a contract for every tool your agent can call
A narrow tool interface turns broad language into bounded operations.
Replace a universal action tool
An illustrative service desk gives its agent a tool named update_system with arbitrary URLs and payloads. That saves initial integration effort but conceals destination, permissions, and side effects. Prefer business-specific tools such as propose_request_assignment or read_approved_status. Each should state which records it can reach and which consequences it can create. A narrow tool is easier to test and explain than a natural-language promise to behave carefully.
Specify what execution must verify
For each tool, record required arguments, allowed values, identity context, preconditions, timeout, and retry behavior. Reject unexpected fields instead of forwarding them to a downstream API. Obtain tenant and caller identity from authenticated context rather than generated text. Return structured outcomes that distinguish denied, invalid, transient failure, and completed. Do not let an error message become a fresh instruction with additional authority.
Workflow at a glance
Make a failure catalogue
Test a missing owner, a forbidden organization, a stale record version, an invalid enum, and a timeout after submission. A well-formed JSON object is not proof that the business operation is valid. For an assignment tool, verify that the destination employee still belongs to the customer and may see the record. OWASP authorization guidance supports checking access on each request; these fixtures turn that principle into acceptance evidence.
Keep the interface maintainable
Version the tool contract when meaning changes, not just when a field is renamed. Old queued jobs should either retain a compatible executor or stop with a clear migration state. Give support staff examples of accepted and rejected actions. More narrow tools can increase maintenance, so group operations by stable business purpose rather than creating a tool for every button. The objective is bounded authority, not a large catalog.
A contract card in the handover
Give the customer one card per tool showing purpose, allowed records, reviewer, and failure route. Tie its technical schema to the same version. The card helps an operator decide whether a proposed use fits existing scope or needs a separately reviewed capability, without guessing from a broad tool name.
Sources and further reading
- Authorization Cheat SheetAuthorization Cheat SheetOWASP · Documentation ·
- LLM Prompt Injection Prevention Cheat SheetLLM Prompt Injection Prevention Cheat SheetOWASP · Documentation ·
Editorial approach
AI-assisted original writing, checked against linked public sources. Practical recommendations and illustrative scenarios are editorial analysis, not reported client results. Source dates and product details may differ from this collection’s preparation date.