Worked engineering guide · October 29, 2026
Review a tool’s permissions before an agent can execute it.
A generated schema describes a call. It does not decide who may make that call, confirm a payment, or undo a deletion. Use this review to turn a small API inventory into explicit runtime requirements.
By Alinafe Matenda. Examples use invented customer and invoice operations; no customer records or production credentials are required.
Start with three operations, not a readiness score.
Our downloadable synthetic input contains a read, a refund and a deletion. The actual compiler output excerpt records the generated names, methods, paths and risk hints. Automated tests compare this excerpt with the compiler so it cannot silently become a different example.
- GET /invoices/{invoiceId}
read; confirmation hint false. This says the declared HTTP method reads information. It does not prove the response is public or free of financial information.- POST /invoices/{invoiceId}/refund
sensitive_write; confirmation hint true. “Refund” triggers the compiler’s keyword heuristic. A real implementation must also check the account, amount, currency and refund state.- DELETE /customers/{customerId}
destructive; confirmation hint true. The HTTP method marks this as destructive. It does not establish whether the upstream deletion is reversible.
A high readiness score is a contract heuristic, not a security certification. A declared auth policy can improve that score without enforcing any authorization. Review the operation and its runtime separately.
For a read: constrain the object and the returned fields.
Imagine an assistant asked to summarize invoice invoice_demo_7. Before executing, the server should derive the caller’s account from its authenticated session, then confirm that this invoice belongs to that account. Checking only that the identifier is well formed leaves cross-account access possible.
Define the smallest response the task needs: perhaps invoice status and totals, rather than billing addresses or payment details. Decide whether logs need an object identifier, a redacted event, or neither. Never paste real invoice bodies into a public issue to prove the tool works.
Acceptance evidence: a synthetic invoice belonging to a different account is denied, while the permitted invoice returns only the agreed fields. A successful HTTP response alone is insufficient.
For a refund: confirm the exact effect and handle retries.
A confirmation prompt should identify the invoice, amount and currency and explain what happens next. “Allow this tool?” hides the decision. Bind an approved action to those specific values so changing the amount invalidates that approval.
Decide what happens if the upstream refund succeeds but the client times out. A retry with the same idempotency key should resolve the existing action rather than issue a second refund. The generated POST hint does not implement idempotency or a payment ledger.
Acceptance evidence: a sandbox test repeats the same synthetic request after a simulated lost response and observes one refund. Verify decline, timeout and mismatched-account behavior too. This guide does not execute payments or authorize a real refund.
For a deletion: establish recoverability before approval.
Write down whether the upstream system archives a record, soft-deletes it, or permanently removes it. Explain related records, exports and retention rules that may be affected. If you cannot establish those effects, stop at a preview of the proposed action.
The compiler marks DELETE as idempotent by method. Repeating the call may lead to the same final absence; that does not make the first call harmless or reversible. A restore procedure is a separate capability that must be tested independently.
Acceptance evidence: use disposable fixtures to verify object ownership, approval binding, the denied path and any claimed recovery procedure. Keep the audit record useful without logging secrets or an entire private record.
Record the release decision in a small review table.
For each generated tool, record its upstream effect, required role, allowed object scope, confirmation fields, retry behavior and a link to the relevant test result. Mark unknowns explicitly. An operation with an unresolved boundary should remain unavailable to the agent even when its schema compiles.
Repeat this review when an operation changes method, permissions, required inputs or response fields. Diffing generated contracts can point to a change; it cannot replace reviewing the underlying implementation.
Alinafe returns contracts and heuristic risk labels. Authentication, authorization, execution, confirmations, retention and recovery remain the runtime operator’s responsibility. See how the conversion works and the API documentation for the shipped format.