Tool Contracts for Reliability

Tool calling should use strict schemas, deterministic validation, and safe fallbacks. The model proposes; your code disposes. Never let unvalidated model output call privileged systems directly.

Defining Tools in the Converse API

toolConfig={
  "tools": [{
    "toolSpec": {
      "name": "create_incident",
      "description": "Open an incident ticket for a degraded service",
      "inputSchema": {"json": {
        "type": "object",
        "properties": {
          "service":  {"type": "string", "enum": ["checkout", "search", "auth"]},
          "severity": {"type": "string", "enum": ["P1", "P2", "P3"]},
          "summary":  {"type": "string", "maxLength": 200}
        },
        "required": ["service", "severity", "summary"]
      }}
    }
  }]
}

When the model responds with stopReason: "tool_use", you receive a structured toolUse block. Your runtime then validates, executes, and returns a toolResult message - the model never touches your systems directly.

The Validation Gauntlet (Every Call, Every Time)

1. Schema validation - does the input parse against the declared JSON Schema? Enums respected, lengths capped?
2. Policy check - is this tool allowed for this user/tenant/agent state? (e.g. P1 creation may require prior diagnosis step)
3. Semantic sanity - does the referenced entity exist? Is "checkout" actually degraded per monitoring?
4. Execution with authorization - the tool runs under your scoped credentials, never model-supplied ones.
5. Structured result back - return outcome or a typed error the model can reason about.

Contract Contents Checklist

• Input and output schema (the model needs to know what comes back).
• Failure behavior - what the model should do on NOT_FOUND vs PERMISSION_DENIED vs TIMEOUT.
• Side-effect classification - read-only tools can auto-run; mutating tools may need approval gates.