Tools Reference - Shanone Documentation

The three Analytics tools are added in the Node.js 0.7.0 / Python 0.4.0 source release. Remote deployment and npm/PyPI publication are separate steps. Check your endpoint’s tools/list for availability.

Parameters, plan availability, billing, and usage accounting for the 32 Remote MCP tools. This reference describes Remote MCP over Streamable HTTP. Local proxies differ by package and version; check your server’s tools/list for the actual tools and schemas. Plan availability does not grant authorization: API-key scopes, user permissions, access to the target resource, and provider connections still apply. “Billable” means consuming a Tool Call from your plan allowance, not necessarily an additional monetary charge. Administration and connection diagnostics are non-billable. All 13 skill tools require Plus or above and consume one Tool Call only on success. Free users can discover skill names, descriptions, and input schemas. Execution is rejected with PLAN_UPGRADE_REQUIRED before accessing skill data. Signing in again does not resolve a plan restriction. Results vary by tool: Markdown text, text containing JSON, or structured errors. Skill plan denials and operation failures use MCP isError: true. For execution tools, also inspect JSON fields such as status, success, and reason, plus the provider result.

Plans, billing, and Analytics

Tool	Plans	Billing	Analytics
`shanone_health_check`	Free and above	Non-billable	Call recorded
`shanone_search_tools`	Free and above	Non-billable	Call recorded
`shanone_list_service_tools`	Free and above	Non-billable	Call recorded
`shanone_get_tool_schema`	Free and above	Non-billable	Call recorded
`shanone_list_connections`	Free and above	Non-billable	Call recorded
`shanone_check_connection`	Free and above	Non-billable	1 parent call; no probe counts
`shanone_execute_tool`	Free and above	Per executed tool	Executed tool name
`shanone_get_tool_usage`	Plus and above	1 on success, per page	Read operation recorded; fetched payloads not copied
`shanone_search_tool_logs`	Plus and above	1 on success, per page	Read operation recorded; fetched payloads not copied
`shanone_get_tool_log`	Plus and above	1 on success, per page	Read operation recorded; fetched payloads not copied
`shanone_list_skills`	Plus and above	1 on success	Call recorded
`shanone_get_skill`	Plus and above	1 on success	Call recorded
`shanone_create_skill`	Plus and above	1 on success	Call recorded
`shanone_update_skill`	Plus and above	1 on success	Call recorded
`shanone_delete_skill`	Plus and above	1 on success	Call recorded
`shanone_list_skill_files`	Plus and above	1 on success	Call recorded
`shanone_read_skill_file`	Plus and above	1 on success	Call recorded
`shanone_write_skill_file`	Plus and above	1 on success	Call recorded
`shanone_delete_skill_file`	Plus and above	1 on success	Call recorded
`shanone_grep_skill`	Plus and above	1 on success	Call recorded
`shanone_create_skill_folder`	Plus and above	1 on success	Call recorded
`shanone_delete_skill_folder`	Plus and above	1 on success	Call recorded
`shanone_rename_skill_path`	Plus and above	1 on success	Call recorded
`shanone_list_services`	Free and above	Non-billable	Call recorded
`shanone_list_user_tool_permissions`	Free and above	Non-billable	Call recorded
`shanone_set_user_tool_permission`	Free and above	Non-billable	Call recorded
`shanone_set_user_service_permission`	Free and above	Non-billable	Call recorded
`shanone_get_permission_summary`	Free and above	Non-billable	Call recorded
`shanone_batch_set_user_permissions`	Free and above	Non-billable	Call recorded
`shanone_get_tool_parameter_policy`	Free and above	Non-billable	Call recorded
`shanone_set_tool_parameter_policy`	Free and above	Non-billable	Call recorded
`shanone_delete_tool_parameter_policy`	Free and above	Non-billable	Call recorded

Normal provider tools are generally billable on success and provider errors, with exceptions such as internal errors. Pre-execution rejection such as a missing account selection is not counted as execution usage. Connection checks record one non-billable parent call regardless of the number of accounts, and retain individual probe outcomes in the diagnostic result. Unauthenticated requests, unknown MCP tools, and schema validation failures that do not reach execution are not counted as Tool Calls. Newly instrumented tools do not receive retroactive usage history.

Health Check

shanone_health_check

Check MCP connectivity, API-key authentication, and backend health. No provider credentials are tested. No parameters. Pass {}.

Tool Vendor

See MCP overview for version and rollout compatibility. For endpoints that have not been updated, follow their actual tools/list definitions.

shanone_search_tools

Search integration tools by keyword, ranked by relevance. The same response includes input schemas for top candidates, so a result with inputSchema can be executed without a separate schema request. Use shanone_list_service_tools for a complete service listing.

Parameter	Type	Required / default	Description
`query`	string	Required	A specific description of the operation you want to perform.
`service`	string	`""`	Exact service identifier, such as linear or gmail. Specify it when known to narrow search and initial provider loading.
`limit`	integer	`20`	Maximum results per page, from 1 to 100.
`offset`	integer	`0`	Number of results to skip, at least 0.
`schema_limit`	integer	`3`	Number of top candidates to include schemas for, from 0 to 5. Set 0 to disable inline schemas.

{
  "query": "list teams",
  "service": "linear",
  "limit": 5,
  "schema_limit": 3
}

Search returns JSON text containing tools, total, query, service, offset, limit, has_more, and next_step instructions. Each tool contains name, service, description, and one of these fields:

Field	Next action
`inputSchema`	Call `shanone_execute_tool` directly with an `arguments` object matching this complete JSON Schema.
`schemaRef`	The value is the exact tool name. Fetch it with `shanone_get_tool_schema` before executing.

The combined inline schemas have a 24,000 UTF-8 byte budget. Results outside the requested top candidates, oversized schemas, and schemas that could not be retrieved use schemaRef. Required fields and constraints are never removed to fit the budget. This budget covers schemas, not the entire search response. Schemas reflect the calling user’s parameter policies. Reuse known schemas for subsequent calls in the same user context, refreshing them when they change. Authorization and parameter policies are still enforced at execution time. For example, if the search result for linear_list_teams includes inputSchema, execute it in the next call:

{
  "tool_name": "linear_list_teams",
  "arguments": {}
}

This reduces the usual search → schema retrieval → execution path to two calls: search with schema → execution. Authentication and prerequisite data lookups may still require additional calls.

shanone_list_service_tools

List tools for one service with pagination. Follow subsequent pages to retrieve the full list.

Parameter	Type	Required / default	Description
`service`	string	Required	Exact service identifier, such as gmail or slack.
`limit`	integer	`50`	Maximum results per page. Maximum 200.
`offset`	integer	`0`	Number of results to skip.

shanone_get_tool_schema

Fetch the input JSON Schema when search returns schemaRef instead of inputSchema, or to refresh a known schema. This tool remains available; it is not required after every search.

Parameter	Type	Required / default	Description
`tool_name`	string	Required	Exact tool name, such as gmail_get_profile.

Connections

shanone_list_connections

List saved connections visible to the caller. Stored configuration is not proof that authentication still works.

Parameter	Type	Required / default	Description
`service`	string	`""`	Exact service identifier, such as gmail or slack.

{
  "service": "gmail"
}

Only IDs with supports_account_selection: true can be passed to execute_tool. Multiple-account selection currently supports Gmail. A legacy:<service> ID identifies a single connection for diagnostics; use it with check_connection, not execution account selection. Requires API-key scope integrations:read or all.

shanone_check_connection

Verify saved connections using read-only provider APIs. Omitting service checks all connected services, with pagination.

Parameter	Type	Required / default	Description
`service`	string	`""`	Exact service identifier, such as gmail or slack.
`connection_id`	string	`""`	Saved connection identifier.
`offset`	integer	`0`	Number of results to skip.
`limit`	integer	`10`	Maximum results per page. Maximum 20.

{
  "service": "gmail",
  "offset": 0,
  "limit": 10
}

Use connection_id to check one account. A page contains at most 20 connections, with three probes running concurrently and a 30-second timeout per probe. Requires integrations:read and tasks:create, or all, plus permission for the probe tool. Results include verified, reauth_required, insufficient_permissions, permission_denied, rate_limited, temporarily_unavailable, verification_failed, unsupported, and not_connected. verified means the named read-only probe succeeded, not that every API operation or permission is available. Unsupported probes are not reported as successful.

Execution

shanone_execute_tool

Execute an integration tool. Inspect both the execution envelope and the provider result; completing a tool invocation does not by itself prove the provider operation succeeded.

Parameter	Type	Required / default	Description
`tool_name`	string	Required	Exact tool name, such as gmail_get_profile.
`arguments`	object	Required	Integration tool arguments as a JSON object; use `{}` for no arguments.
`session_id`	string	`""`	Optional legacy execution/session identifier. It does not select an OAuth account; omit for a stateless call.
`connection_id`	string	`""`	Required for Gmail execution. Use an ID whose supports_account_selection is true.
`request_id`	string	`""`	Optional retry identifier. Reuse only for the same request, arguments, and account; do not reuse for a different operation.

{
  "tool_name": "gmail_get_profile",
  "arguments": {},
  "connection_id": "conn_example"
}

Updated Remote MCP, Node.js, and Python implementations all advertise object arguments. Legacy JSON strings are accepted during migration, but new calls should not serialize the object. Arrays, null, scalars, and malformed JSON strings are rejected before provider execution. Reconnect after updating to refresh tools/list. For Gmail, obtain an account ID with list_connections and provide it on each call. Omitting it returns CONNECTION_SELECTION_REQUIRED. To use another account, change the ID on the next call. execution_context_id is no longer supported. For auth_required / auth_expired, follow the returned connection instructions. For confirmation_required, obtain confirmation and retry with "confirm": true in the same arguments. Usage is recorded under the executed tool’s name, without an additional execute_tool charge or count.

Skill Vendor

All 13 tools require Plus or above and are billable only on success. Skill ownership and resource-sharing permissions still apply.

shanone_list_skills

List saved skills, newest first. The query is optional; an empty query lists your saved skills with pagination.

Parameter	Type	Required / default	Description
`query`	string	`""`	Search text; empty where optional.
`limit`	integer	`20`	Maximum results per page. Maximum 100.
`offset`	integer	`0`	Number of results to skip.

shanone_get_skill

Read a skill’s name, summary, and full instructions. The agent follows the instructions itself; this call does not execute the workflow.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.

shanone_create_skill

Create a reusable skill. All three fields must be non-empty. description and body are stored as summary and instructions.

Parameter	Type	Required / default	Description
`name`	string	Required	Skill name.
`description`	string	Required	What the skill does and when to use it.
`body`	string	Required	Skill instructions.

{
  "name": "Weekly report",
  "description": "Prepare a weekly status report.",
  "body": "Read the relevant issues and summarize the completed work."
}

shanone_update_skill

Update an existing skill. Only non-empty optional fields are changed; empty strings leave the existing values unchanged.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.
`name`	string	`""`	Skill name.
`summary`	string	`""`	Updated skill description.
`instructions`	string	`""`	Updated skill instructions.

shanone_delete_skill

Permanently delete a skill.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.

shanone_list_skill_files

List additional files bundled with a skill, including paths and sizes. The main instructions are read with get_skill.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.

shanone_read_skill_file

Read a text file bundled with a skill. Binary files return a description instead of their contents; use the dashboard to view or download them.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.
`path`	string	Required	Path relative to the skill directory, such as references/guide.md.

shanone_write_skill_file

Create or overwrite a UTF-8 text file. Missing parent folders are created automatically.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.
`path`	string	Required	Path relative to the skill directory, such as references/guide.md.
`content`	string	Required	Full UTF-8 text to write. Existing file content is replaced.

{
  "skill_id": "skill_example",
  "path": "references/checklist.md",
  "content": "Review completed tasks.\n"
}

shanone_delete_skill_file

Delete one file bundled with a skill.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.
`path`	string	Required	Path relative to the skill directory, such as references/guide.md.

shanone_grep_skill

Search skill files with a regular expression. Results include file paths and line numbers; narrow the pattern if results are truncated.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.
`pattern`	string	Required	Regular expression to search for.
`path_glob`	string	`""`	Optional file glob, such as references/*.md; empty searches all files.
`case_sensitive`	boolean	`false`	Whether the search distinguishes letter case.

{
  "skill_id": "skill_example",
  "pattern": "completed",
  "path_glob": "references/*.md"
}

shanone_create_skill_folder

Create an empty skill folder. This is optional before writing files because write_skill_file creates parent folders.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.
`path`	string	Required	Path relative to the skill directory, such as references/guide.md.

shanone_delete_skill_folder

Delete a folder and all files and subfolders inside it. This operation cannot be undone.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.
`path`	string	Required	Path relative to the skill directory, such as references/guide.md.

shanone_rename_skill_path

Rename or move a file or folder. Moving a folder moves its contents. An existing destination is rejected rather than overwritten.

Parameter	Type	Required / default	Description
`skill_id`	string	Required	Exact skill ID returned by list_skills or create_skill.
`from_path`	string	Required	Existing relative file or folder path.
`to_path`	string	Required	New relative path; must not already exist.

Permission Vendor

Permission and parameter-policy management, except list_services, requires Root or an SA2 user delegated tool-permissions:ManageOthers. Delegated SA2 users cannot target Root users. All are non-billable.

shanone_list_services

List registered service names, display names, and tool counts. No administrator role is required.

Parameter	Type	Required / default	Description
`limit`	integer	`100`	Maximum results per page. Maximum 500.
`offset`	integer	`0`	Number of results to skip.

shanone_list_user_tool_permissions

List a target user’s tool and service permission overrides.

Parameter	Type	Required / default	Description
`target_user_id`	string	Required	User whose permissions are being inspected or changed.

shanone_set_user_tool_permission

Allow or deny one tool for a target user. A tool override takes priority over a service override or role default.

Parameter	Type	Required / default	Description
`target_user_id`	string	Required	User whose permissions are being inspected or changed.
`tool_name`	string	Required	Exact tool name, such as gmail_get_profile.
`enabled`	boolean	Required	true to allow; false to deny.

shanone_set_user_service_permission

Allow or deny the tools of a service for a target user, subject to individual tool overrides.

Parameter	Type	Required / default	Description
`target_user_id`	string	Required	User whose permissions are being inspected or changed.
`service_name`	string	Required	Exact service name from list_services.
`enabled`	boolean	Required	true to allow; false to deny.

shanone_get_permission_summary

Summarize a target user’s enabled and disabled services and tools.

Parameter	Type	Required / default	Description
`target_user_id`	string	Required	User whose permissions are being inspected or changed.

shanone_batch_set_user_permissions

Apply up to 500 service/tool permission operations in one call. Inspect each operation’s result; one failure does not abort the entire batch.

Parameter	Type	Required / default	Description
`target_user_id`	string	Required	User whose permissions are being inspected or changed.
`operations`	string	Required	Non-empty JSON array string containing type (service or tool), name, and enabled; maximum 500 entries.

{
  "target_user_id": "user_example",
  "operations": "[{\"type\":\"service\",\"name\":\"slack\",\"enabled\":true}]"
}

Parameter Policies

shanone_get_tool_parameter_policy

Read the argument constraints configured for a target user’s tool. Tool access and allowed argument values are separate controls.

Parameter	Type	Required / default	Description
`target_user_id`	string	Required	User whose permissions are being inspected or changed.
`tool_name`	string	Required	Exact tool name, such as gmail_get_profile.

shanone_set_tool_parameter_policy

Set or replace one field’s argument policy. Constraints are applied by the server during execution.

Parameter	Type	Required / default	Description
`target_user_id`	string	Required	User whose permissions are being inspected or changed.
`tool_name`	string	Required	Exact tool name, such as gmail_get_profile.
`field_name`	string	Required	Exact input parameter name to constrain.
`policy_type`	string	Required	One of the policy types listed below.
`policy_value`	string	`"{}"`	Policy configuration as a JSON object string; see the policy table below.

{
  "target_user_id": "user_example",
  "tool_name": "gmail_send_message",
  "field_name": "to",
  "policy_type": "domain_allowlist",
  "policy_value": "{\"values\":[\"example.com\"]}"
}

policy_type	Example policy_value contents (encode as a JSON string)	Meaning
`allowlist / denylist`	`{"values":["a","b"]}`	Allow / reject listed values.
`domain_allowlist`	`{"values":["example.com"]}`	Restrict domains.
`pattern`	`{"value":"^[A-Z].*"}`	Require a regex match.
`range`	`{"min":0,"max":100}`	Bound a numeric value.
`max_length / max_items`	`{"value":200}`	Limit length / item count.
`forced_value`	`{"value":"audit@example.com"}`	Always replace the value.
`forced_append`	`{"value":"audit@example.com"}`	Append the configured value.
`default_value`	`{"value":"user"}`	Fill only when omitted.
`required_override`	`{}`	Require the field.

shanone_delete_tool_parameter_policy

Remove the policy on one field. This does not change the tool’s allow/deny permission.

Parameter	Type	Required / default	Description
`target_user_id`	string	Required	User whose permissions are being inspected or changed.
`tool_name`	string	Required	Exact tool name, such as gmail_get_profile.
`field_name`	string	Required	Exact input parameter name to constrain.

Errors and migration

Result	Action
`PLAN_UPGRADE_REQUIRED`	Upgrade to Plus or above. Denied calls are non-billable.
`TOOL_CALL_LIMIT_EXCEEDED`	Check the plan allowance. The skill operation is not executed or billed.
`SUBSCRIPTION_UNAVAILABLE`	Subscription data could not be verified. Retry later.
`CONNECTION_SELECTION_REQUIRED`	Provide a Gmail ID returned by list_connections.
`CONNECTION_NOT_FOUND` / `connection_not_found`	Check connection ownership and existence. Another account is not selected automatically.
`401` / `403`	Check your API key, organization ID, and permissions. Distinguish transport errors from MCP plan denials.

shanone_create_execution_context, shanone_get_execution_context, and shanone_switch_connection have been removed. Refresh the client’s tool list and migrate to explicit connection IDs. shanone_get_tool_usage is a design proposal, not an available tool. Configure your connection.

Analytics

All three tools require Plus, Pro, Team, or Enterprise. API keys authenticate the caller. Analytics authorization uses the live subscription and user policy; no Analytics-specific key scope, permission migration, or key reissue is required. Plan access does not grant user permissions. The existing Root/SA2 policy engine evaluates user/group policies, permission boundaries, and organization controls. No roles or policies are automatically granted by this release.

Operation	Required user actions
Usage, self	`analytics:Overview`
Search/detail, self	`analytics:Logs`
Any organization-wide read	Above action plus `analytics:Users`
Include saved request/response	Above actions plus `analytics:ReadLogPayload`

Organization and caller IDs are resolved server-side; arbitrary user/organization IDs are not accepted. Scope and permissions are checked again for each page. Knowing a log ID does not grant access. Each successful call consumes one Tool Call, including zero matching records and subsequent pages. Invalid inputs, plan/permission rejection, missing logs, expired cursors, quota rejection, and backend/read-budget failures are not charged. Reservations are canceled on execution failure. Each read is audited without copying the fetched log payloads into its own audit record. The current read is outside its own fixed as_of window and appears in later usage queries.

shanone_get_tool_usage

Returns totals, grouped rows, period, as_of, next_cursor, complete, read_consistency, coverage, and warnings. Totals cover the full matching period, not just the displayed page. Counts distinguish successful, failed, unknown-status, billable, and non-billable calls. Stored error and failed both count as failed; missing/unrecognized statuses remain unknown. statistics adds duration samples, average/min/max/p95 and error-category counts for the whole result and each group. Each row has a logs_query with the exact filters, and next_steps suggests a failure search when failures exist. Rows sort by count descending, then key ascending.

shanone_search_tool_logs

Returns logs, total_count, and the same period/pagination metadata. Logs sort by timestamp descending with log ID as the tie-breaker. Each row contains log_id, timestamp, tool/service, status, duration, billing flag, connection/session IDs, and an error type when available. Each row also includes execution (metadata summary and error guidance), billing (historical reason or explicit unknown), and a ready-to-use detail_query. No request/response bodies or free-text error messages are returned. Shared parameters for usage and search:

Parameter	Default / limits	Meaning
`days`	Omitted means 7; 1–90	Rolling 24-hour days ending at operation start
`start_time`, `end_time`	Both or neither	ISO 8601 with offsets; positive range ≤90 days, no future end; cannot combine with `days`
`scope`	`self`	`self` or `organization`
`service`	None	Registered service identifier; unknown historical ownership uses `unknown`
`tool_names`	`[]`, max 20	Exact names, including retired tools
`billing`	`all`	`all`, `billable`, `non_billable`
`limit`	20, max 100	Rows per page
`cursor`	None	Opaque continuation token; resend the same parameters

Usage additionally accepts group_by (tool, service, day; default tool) and IANA timezone (default UTC) for day boundaries. Search additionally accepts status (all, success, failed, unknown), connection_id, and session_id. Different filters are AND-combined; tool_names matches any listed name.

{"days":7,"group_by":"day","timezone":"Asia/Tokyo","scope":"self"}

{"days":7,"service":"gmail","status":"failed","limit":20}

Time ranges are start-inclusive/end-exclusive. A five-minute snapshot keeps subsequent pages consistent; every page is reauthorized and separately charged. A cursor is not a durable collection checkpoint. Recent logs may arrive late. Historical retention/instrumentation coverage is reported as unknown, not assumed complete. Missing legacy statuses remain unknown; missing legacy billing flags use the shared Analytics billing fallback. Reads are bounded to 50 database pages, 50,000 evaluated records, and a 10-second budget checked between database operations. If the full period cannot be read, READ_LIMIT_EXCEEDED is returned without partial totals or a charge. Narrow the period. complete: true means the bounded query was exhausted, not that all historical or recently ingested events are present.

shanone_get_tool_log

Parameter	Default	Meaning
`log_id`	Required	ID from search results
`scope`	`self`	`self` or authorized `organization`
`include_payload`	`false`	Include stored, redacted, bounded request/response with additional permission

{"log_id":"LOG_ID_FROM_SEARCH","include_payload":false}

Payload values may be marked not_stored, unstructured_or_truncated, size_limit, or redacted; unavailable content is not reconstructed. Recognized credential keys, token patterns, and URLs are redacted. Structured payload output is limited to 16 KB per field. Existing provider-specific audit redaction still applies. Legacy IDs that are not directly addressable are returned as LOG_NOT_FOUND; this endpoint does not scan the entire table. Permission denials include reason; user-policy denials also include required_action to identify the missing action. Errors use MCP isError: true: PLAN_UPGRADE_REQUIRED, PERMISSION_DENIED, INVALID_ARGUMENTS, INVALID_SERVICE, TOOL_CALL_LIMIT_EXCEEDED, LOG_NOT_FOUND, INVALID_CURSOR, CURSOR_EXPIRED, READ_LIMIT_EXCEEDED, or ANALYTICS_UNAVAILABLE. The local proxies use the same server policy through POST /api/v1/analytics/usage, /logs/search, and /logs/detail.

Reading the response (version 2)

Successful Analytics responses include response_version: 2, query_status: "success", and a short summary. This means the Analytics query succeeded, not that every recorded execution succeeded. A failed Analytics operation uses MCP isError: true and a query_status: "error" error body when it reaches the shared execution policy. Protocol/input validation may reject earlier. Existing fields (totals, rows, logs, status, duration_ms, billable) remain available. Illustrative search row, abbreviated:

{
  "response_version": 2,
  "query_status": "success",
  "summary": "Showing 1 of 1 matching execution logs, newest first.",
  "logs": [{
    "log_id": "log_example",
    "tool_name": "example_update",
    "status": "failed",
    "execution": {
      "status": "failed",
      "recorded_status": "error",
      "duration_ms": 320,
      "summary": "Execution was recorded as failed.",
      "error": {
        "state": "recorded_classification",
        "category": "timeout",
        "message": "The recorded execution timed out.",
        "suggested_action": "Check whether the original operation completed before retrying; a timeout does not prove it had no effect.",
        "automatic_retry": false
      }
    },
    "billing": {
      "billable": true,
      "decision_source": "recorded",
      "reason": "billable_failed_execution",
      "reason_state": "recorded"
    },
    "detail_query": {
      "tool": "shanone_get_tool_log",
      "arguments": {"log_id": "log_example", "scope": "self"}
    }
  }]
}

execution.operation identifies the tool and recorded argument count. execution.result_metadata exposes only recorded argument count, input/output byte sizes, output type, truncation flag, and a top-level collection item count when recorded. The summary does not inspect payload text, claim the intended business outcome happened, or infer affected-record counts. A collection count describes a returned top-level list, not how many records an operation changed. Missing metadata is null. Error guidance comes from the stored classification (rate_limit, timeout, invalid_input, auth_error, internal_error, or unknown). It is a troubleshooting suggestion, not a verified provider-specific root cause or authorization to retry. Success gives error.state: not_applicable; unrecognized execution status gives unknown_execution_status. Metadata alone cannot distinguish an expired credential from every other authorization failure. Free-text error details remain behind include_payload permission and redaction. Usage statistics.duration_ms contains sample_count, missing_count, average, min, max, p95, and percentile_method: nearest_rank. Only finite nonnegative durations are included; absent/invalid values are not treated as zero. With no samples, numeric statistics are null. statistics.errors counts failures by supported classification, including unknown. Statistics cover the full matching result/group, not just the displayed page. rows[].logs_query preserves scope, billing and tool/service filters; day grouping uses the requested timezone and clamps the day to the original period. Following any suggested query still requires permissions and incurs the normal successful-call charge. Detail responses add timings, related_execution (session, retry origin, previous tool and parallel group), availability, and optional next_steps. These reflect stored fields only; they do not fetch other logs automatically. Payload availability is not_requested / permission not_checked by default, and requested / granted after explicit authorized inclusion. A suggested payload query does not imply the caller has that permission. Missing detail fields do not prove deletion or retention expiry; those causes are not distinguishable from missing instrumentation. With payload inclusion, request/response states describe what was actually available. Empty stored strings are not_stored. New execution records persist their billing decision reason:

`billing.reason`	Meaning
`billable_execution`	Successful billable execution
`billable_failed_execution`	Failed execution that was still billable under the decision at execution time
`execution_non_billable_override`	Execution path explicitly forced non-billable accounting
`internal_error`	Billing classified it as a non-billable internal error
`tool_non_billable`	Tool was non-billable at execution time

For older records, reason is null and reason_state is not_recorded; current pricing is never used to invent a historical reason. decision_source: legacy_default indicates the billing flag itself was absent and the shared legacy fallback was applied. Reasons and top-level collection counts become available for newly written records after the relevant execution service is deployed. Older records are not backfilled. Response version 2 uses a separate snapshot binding. Cursors created before this output update must be replaced by a new query; existing authorization, read budgets, payload restrictions, and billing rules still apply.

OpenAI integration tools

OpenAI provides 10 integration tools through shanone_execute_tool: image generation/editing, background research with status/cancellation, transcription, speech generation, and background file analysis with status/cancellation. See the OpenAI tool reference for exact arguments, model constraints, API mappings, output fields and migration notes. These are integration tools, not additional MCP control tools.

​Plans, billing, and Analytics

​Health Check

​shanone_health_check

​Tool Vendor

​shanone_search_tools

​shanone_list_service_tools

​shanone_get_tool_schema

​Connections

​shanone_list_connections

​shanone_check_connection

​Execution

​shanone_execute_tool

​Skill Vendor

​shanone_list_skills

​shanone_get_skill

​shanone_create_skill

​shanone_update_skill

​shanone_delete_skill

​shanone_list_skill_files

​shanone_read_skill_file

​shanone_write_skill_file

​shanone_delete_skill_file

​shanone_grep_skill

​shanone_create_skill_folder

​shanone_delete_skill_folder

​shanone_rename_skill_path

​Permission Vendor

​shanone_list_services

​shanone_list_user_tool_permissions

​shanone_set_user_tool_permission

​shanone_set_user_service_permission

​shanone_get_permission_summary

​shanone_batch_set_user_permissions

​Parameter Policies

​shanone_get_tool_parameter_policy

​shanone_set_tool_parameter_policy

​shanone_delete_tool_parameter_policy

​Errors and migration

​Analytics

​shanone_get_tool_usage

​shanone_search_tool_logs

​shanone_get_tool_log

​Reading the response (version 2)

​OpenAI integration tools

Plans, billing, and Analytics

Health Check

shanone_health_check

Tool Vendor

shanone_search_tools

shanone_list_service_tools

shanone_get_tool_schema

Connections

shanone_list_connections

shanone_check_connection

Execution

shanone_execute_tool

Skill Vendor

shanone_list_skills

shanone_get_skill

shanone_create_skill

shanone_update_skill

shanone_delete_skill

shanone_list_skill_files

shanone_read_skill_file

shanone_write_skill_file

shanone_delete_skill_file

shanone_grep_skill

shanone_create_skill_folder

shanone_delete_skill_folder

shanone_rename_skill_path

Permission Vendor

shanone_list_services

shanone_list_user_tool_permissions

shanone_set_user_tool_permission

shanone_set_user_service_permission

shanone_get_permission_summary

shanone_batch_set_user_permissions

Parameter Policies

shanone_get_tool_parameter_policy

shanone_set_tool_parameter_policy

shanone_delete_tool_parameter_policy

Errors and migration

Analytics

shanone_get_tool_usage

shanone_search_tool_logs

shanone_get_tool_log

Reading the response (version 2)

OpenAI integration tools