Skip to content
SmartSite Assistant SmartSite Assistant

Operate Tools as public integrations

Production posture

The model is a caller, not a security boundary.

Visitors influence the conversation; the conversation influences Tool calls. Treat the Tool definition as an integration client and the receiver as the final authority. Clear descriptions improve selection, but security comes from narrow exposure, validation, authentication, authorization, network controls, idempotency, and evidence.

Think of each enabled Tool as a public integration

Section titled “Think of each enabled Tool as a public integration”

Ask four questions before configuration:

  1. What data can this return to an unauthenticated visitor?
  2. What is the largest real-world change it can cause?
  3. What happens if its arguments are wrong, hostile, or repeated?
  4. Who can disable it and investigate at both ends?

A “read-only” WP Option can be more dangerous than a tightly scoped email because it may reveal a token. A GET webhook can still be harmful if the endpoint changes state incorrectly. A Description that says “only for customers” cannot know whether the visitor is a customer.

The preflight before a Tool goes live

Section titled “The preflight before a Tool goes live”
Production gate
Control areaPass conditionEvidence to retain
Purpose and type One narrow public outcome; correct data/lookup/action classification. Approved capability statement and owner.
Exposure Enabled only when ready and assigned to the smallest useful Assistant/specialist. Tool list state and published flow revision if used.
Data minimization Returned values and submitted fields contain only what the outcome needs. Sanitized admin test result and receiver payload sample.
Authentication Webhook/Hook destination recognizes the calling integration securely. Receiver configuration and key-rotation owner—not the secret itself.
Authorization Receiver checks whether this operation is allowed for the relevant record/context. Denied test case and policy owner.
Validation Length, format, allowed values, ownership, and state transitions are checked remotely. Valid, missing, malformed, boundary, and hostile test results.
Network safety Public HTTPS endpoint; WordPress safe remote requests remain enabled. Endpoint review and an unsafe/private-target rejection test.
Duplicate safety Repeated calls are rejected or idempotent. Two-call test showing one final side effect.
Truthful results Messages distinguish transport acceptance from delivery/business completion. Expected success, rejection, timeout, and error copy.
Observability and shutdown Chat History and receiver logs can correlate an event; named admin can disable quickly. Runbook, retention decision, and kill-switch owner.

Runtime boundaries you must account for

Section titled “Runtime boundaries you must account for”

Disabled Tools are not exposed to normal runtime execution, making the list toggle the first containment control. Assistant assignment reduces where a Tool definition is available. Advanced flow assignment narrows it to specialist(s) in a published workflow.

These are exposure controls, not visitor identity. In Basic runtime, action Tools do not pass through a separate visitor-approval gate. In Advanced runtime, email, non-GET webhook, and WordPress Hook actions receive confirmation/duplicate protection when correctly connected. A GET webhook remains a lookup. Always make the receiver safe even if a caller bypasses conversational expectations.

Rate limits reduce volume; they do not authorize an action. Required parameters prevent obvious missing values; they do not verify account ownership. Sequential Tool execution does not prevent a repeated conversation or network retry.

Network safety and the unsafe bypass

Section titled “Network safety and the unsafe bypass”

Webhooks use WordPress safe remote request behavior by default, which validates destinations and helps block server-side requests into unsafe/private targets. Keep this protection on for public HTTPS services.

Allow unsafe HTTP switches to ordinary remote requests and bypasses those URL safety checks. It can make internal services reachable through a visitor-influenced operation and increase server-side request forgery risk. Use it only for a controlled local/private development need with a reviewed fixed endpoint. Never check it merely to make a failing production endpoint “work.”

When something goes wrong: contain first

Section titled “When something goes wrong: contain first”
  1. Disable the Tool. Use the list toggle before editing descriptions or retesting.
  2. Limit the receiver. Revoke/rotate the integration credential, disable its route, or switch the target to maintenance mode if impact may continue.
  3. Preserve evidence. Record time range, Tool ID/name, active runtime/Assistant/flow revision, sanitized arguments/result, conversation log ID, and receiver request ID.
  4. Classify impact. Data disclosure, unauthorized change, duplicate action, incorrect recipient, network reach, or availability failure require different owners.
  5. Find the failed control. Exposure, model routing, parameter design, receiver validation, authorization, network safety, or result interpretation.
  6. Repair in a sandbox. Test both the triggering case and adjacent abuse/failure cases.
  7. Review affected records. Notify the appropriate privacy/security/business owner; do not erase evidence to make the dashboard look clean.
  8. Re-enable deliberately. Use a monitored window and confirm both SmartSite and receiver logs.

Do not begin an incident by rewriting the Description while leaving the action enabled. Description changes influence future model decisions; they do not stop a direct ongoing receiver problem or revoke a leaked credential.

Symptom-led troubleshooting

Section titled “Symptom-led troubleshooting”
From symptom to the narrowest useful check
SymptomInspect firstLikely correction
Tool is never called Enabled state, Assistant assignment, active Assistant, Description overlap, saved parameters, and advanced specialist connection. Expose it to the intended runtime and clarify exact intent without making it broad.
Tool is called for general questions Description and neighboring Tools with similar names/intents. Disable, distinguish data lookup from action, and add explicit “do not use for” scope.
Required values are rejected Exact argument keys, blanks/unknown markers, and email validity. Correct parameter name/type/description; do not mark optional filler required.
WP Option leaks internal fields The complete option value. Disable immediately; rotate exposed credentials and replace with curated Static Data or a filtered integration.
Webhook is blocked before connection Public HTTPS URL, DNS, redirect, and safe-remote validation. Fix the endpoint. Do not enable unsafe HTTP unless this is an approved controlled private-development target.
Webhook returns non-2xx or times out Receiver logs, method, header JSON, body format, auth, payload, and 15-second limit. Correct receiver contract and return a fast explicit response.
Webhook returns 2xx but operation failed Business status inside response and receiver state. Make the API use truthful status codes/results and validate completion before telling the visitor.
Email Tool says success but no message arrives WordPress/mail-provider logs, spam, sender authentication, recipient, and queue. Repair deliverability; rewrite success language so acceptance is not called delivery.
WordPress Hook says executed but nothing happened Exact smartsite_tool_ filter registration and callback return/side effect. Have a developer implement and verify the callback; do not trust generic success.
Action happens twice Repeated visitor turn, retry path, duplicate IDs, and receiver idempotency. Use a stable operation key or receiver-side duplicate detection.

A threat review for nontechnical administrators

Section titled “A threat review for nontechnical administrators”

You do not need to write code to ask useful security questions:

  • Could a stranger cause this action? If yes, is that intended?
  • Could changing one parameter target another person’s record?
  • Does the receiver check that relationship, or merely trust the submitted ID?
  • What private data appears in a success result or error body?
  • Could repeating “yes” create two emails, leads, refunds, or bookings?
  • Who notices if the endpoint has been failing for a day?
  • Is the unsafe HTTP checkbox off?
  • Can you name the person who will disable the Tool during an incident?

If the technical owner cannot give concrete answers, keep the Tool disabled. “The AI should know” is not a control.

Logs, privacy, and useful evidence

Section titled “Logs, privacy, and useful evidence”

Chat History can show Tool activity, arguments/result metadata, runtime routing, errors, and Advanced flow traces where available. The receiver should keep its own request/outcome log. Correlate by time and a safe request identifier; avoid logging credentials or unnecessary personal data.

Retention should match purpose. Enough evidence to investigate does not mean keeping full visitor payloads forever. Follow the site’s privacy and incident procedures, especially when an action contains contact details.

Change management is also a security control

Section titled “Change management is also a security control”

Renaming a Function Name, changing parameter keys, deleting a Tool, rotating a webhook endpoint, or moving an Assistant assignment can break dependent templates and Advanced flows. Make these changes in a maintenance window, keep the Tool disabled while dependencies are updated, run Flow Checks, publish the new revision when appropriate, and repeat end-to-end tests.

Deletion removes the Tool definition; it does not undo emails already sent, remote records already created, or data already disclosed. For an incident, contain the receiver and handle affected records before cleaning configuration. Preserve enough sanitized evidence to explain what happened.

The kill switch in context

Section titled “The kill switch in context”
Tool Security and Troubleshooting
Capture
Show the Tools list with one fictional action tool disabled and its assignment/status columns visible.
Show
Tool name/type, assistant assignment, Enabled toggle, Edit, Test
Viewport
Desktop, 1440 × 900
Annotate
Use numbered callouts only for controls referenced in the procedure.
Redact
OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text

Return to the control you need

Section titled “Return to the control you need”