Skip to main content

​
Be task-shaped, not tool-shaped

shanone_search_tools is relevance-ranked against a description of the task, not a lookup by tool name. A specific, task-shaped query returns a small, usable set of results; a bare service name on a large integration (Slack has 139 tools, Stripe has 328) can return too much or the wrong thing.
“Post a message to a Slack channel”“Create a GitHub issue with a title and body”“Get the ETH balance of an address”

​
Ask for a full listing when you mean “everything”

If you (or your agent) actually want the complete set of tools for a service — not just the most relevant few — say so explicitly, and have the agent call shanone_list_service_tools instead of shanone_search_tools. This matters most for large integrations: shanone_search_tools is not guaranteed to surface every tool for services this size — check has_more in the response, and if it’s true, either narrow the query or switch to shanone_list_service_tools.

​
Let the schema step do its job

For unfamiliar tools, have your agent call shanone_get_tool_schema before shanone_execute_tool. This avoids guessed argument names (Shanone tools use descriptive but not always obvious field names — e.g. slack_post_message takes channel, not channel_id) and surfaces required vs. optional fields up front.
1

Search

shanone_search_tools with a task-shaped query.
2

Inspect (when unsure)

shanone_get_tool_schema with the exact tool name from the search result.
3

Execute

shanone_execute_tool with a JSON string of arguments matching the schema.

​
Save workflows as Skills, don’t repeat yourself

If you find yourself giving your agent the same multi-step instructions more than once (e.g. “check the Notion project page, summarize it, post to Slack”), save it with shanone_create_skill. Skills are stored server-side, so the same workflow is available from any machine, IDE, or agent that connects to your Shanone account — and it shows up in Shanone’s web dashboard too.

Check first

Call shanone_list_skills before starting a non-trivial multi-step task — someone on your team may have already saved it

Name things clearly

A Skill’s name and summary are the only things shown in list results — make them specific enough to recognize later

​
Handle the auth wall gracefully

When shanone_execute_tool returns reason: "auth_required" or "auth_expired", that’s not a failure to work around — it’s Shanone telling you the service isn’t connected yet. Surface the connect_link to the user, wait for them to complete OAuth, then retry the exact same tool call.
Don’t ask your agent to try alternate tools or workarounds when it hits auth_required. The fix is always: visit the connect link, then retry.

​
Keep permissions least-privilege

If you’re a Root user or a delegated SA2 administrator, resist enabling every service for every teammate by default. Use shanone_set_user_service_permission to disable services a role doesn’t need (e.g. billing tools for engineers, infra tools for sales), and reserve shanone_batch_set_user_permissions for onboarding a new hire’s whole permission set in one call. See Permissions & Access Control for the full model.

​
Common pitfalls