run-tool

# Run a Sim Integration Tool Sim holds the credentials. Read what the tool declares, bind auth from that declaration, and run it. Never put a live credential in the command. ## Preflight - `tools execute` requires a personal API-key profile; a workspace API key is refused. - Find the tool with `sim --output json tools list --search <term>`, then read it with `sim --output json tools get <toolId>`. Never guess a tool id or a parameter name. - An unversioned name resolves to the newest version visible in the workspace, and the response echoes the id that answered. Use that id in the call. - Use a Function block for code requiring workflow execution context. An executor-delegation error from `function_execute` is not a missing user credential; do not invent internal context fields or change authentication to bypass it. ## Bind auth from the declaration, not from habit `tools get` labels every parameter with a `visibility`, and the label says where its value comes from: - `user-or-llm` — you supply it in `--input`. - `user-only` — you supply it, but pass a reference instead of the secret: `{{VAR_NAME}}` as the whole value, resolved server-side. List the available names with `sim --output json secrets list`; values are never returned. Any other value is sent verbatim. One exception: a parameter named `credential` or `oauthCredential` is the credential selector, not a secret — see below. It is refused in `--input`. - `hidden` — Sim fills it. Never put it in `--input`; it is refused. Then bind the credential by the tool's own shape: - The tool declares `oauth.required`, **or** declares a required `credential` or `oauthCredential` parameter (Snowflake and others do the latter, with no `oauth` block) — find the credential with `sim --output json credentials list --provider-id <provider>` and pass `--credential-id`. It is the one place a credential is named; Sim places it where the tool expects it. Omitting it fails naming `credentialId`; putting it in `--input` under any spelling is refused. - `hostedApiKey` is `always`, or `conditional` and this call matches — omit the key entirely; Sim supplies its own and bills the workspace. - Otherwise the tool takes its own `user-only` key parameter; pass a `{{VAR_NAME}}` reference. Your Sim login governs platform access; the selected provider credential determines the external identity. A different OAuth connection can act as a different bot or user. Do not substitute one to bypass an ownership error or a mismatch between advertised and accepted authentication modes. `--input` accepts exactly what `tools get` publishes as yours to send. An undeclared key, a `hidden` one, or a credential under any name is a `400` that names the offending field — read it rather than guessing at a spelling. ## Run and read the outcome ```bash sim --output json tools execute <toolId> --credential-id <id> --input '{"...": "..."}' ``` `--input` also accepts `@path` or `@-`, which is how a payload too large or too awkward to quote reaches the command. A tool result with `status: "failed"` exits non-zero and reports its reason in `error.message`. Read that reason to distinguish execution setup failure from a provider refusal; the status alone does not prove the service received the request. A `403` carrying `error.details.code` `INTEGRATION_NOT_ALLOWED` is a workspace policy decision, not a fixable argument — say so and stop. Tool results follow the provider's pagination contract. When more pages remain, use the published cursor before reporting a total; the CLI's resource-list pagination does not paginate tool results. ## Invariants - Never print a resolved secret, an OAuth token, or a profile credential. You hold a credential id and a variable name; that is all the call needs. - Do not retry a failed write blind. A tool call is not idempotent, and a retry can duplicate the message, issue, or record the first attempt created. - Build a workflow instead when the task needs more than one call, branching, or a schedule.